onlyforbopi
1/28/2019 - 10:14 AM
PGP / GPG / GNUPG
- Theory.bsh - All relevant theory, including basic cipher theory.
- Basicprep.bsh - All basic setup and preparation needed to be done.
- Encrypt.bsh - How to encrypt (Asymmetric / PublicPrivate key)
- Decrypt.bsh - How to decrypt (Asymmetric / PublicPrivate key)
- pgpadvanced.bsh - Advanced Functions of pgp / gnupg
- pgpgpgsoftware.bsh - Relevant software and setup information
- Pgpstandard.bsh - Links to the openpgpstandard.
- GPGdebug.bsh - Popular errors and their fixes.
- GPGzip.bsh - The gpgzip tool for gpg, encrypt into an archive.
- Symmetric.bsh - Details symmetric encryption using pgp
- GPGmanpage - Basic command and manual to gpg
- FullManGNU - GnuPrivacyGuard Full Manual
- SimpleEncryptionTest - Test your own Public/Private Key Pairs.
- UseStrongerAlgorithm - Set cipher and digest algorithm usage order (SHA256, AES256 etc)
- PassingPasswordScript - Various ways to pass your private key password so you can script gpg
- ControlCompressionLvl - How to control compression algorithm and level
- CommonlySeenProbs - GPG Commonly seen problems.
- GPGMigrationFullBlueP - GPG Migration Full Blueprint
###############################################
#Generate new key-pair
gpg --gen-key
# RSA/RSA
# 2048?
# Validity? Poso 0 for not expire
# Associate with user
# + password
################################################
# Check existence of generated key
gpg --list-keys
################################################
# Generate revocation certificate for key.
gpg --output revoke.asc --gen-revoke <mykey>
################################################
# Export public key from keychain (To be used by others)
#binary
gpg --output alice.gpg --export alice@cyb.org
#ascii-armored
gpg --output alice.asc --armor --export alice@cyb.org
################################################
# Importing public key
# Key will be in file: *.gpg or *.pgp or *.asc
gpg --import blake.gpg
# blake.gpg = <filename>
# Check that key was successfully imported:
gpg --list-keys
################################################
# Validate imported key with sender
# Keys needs to be signed by the user as trustworthy.
gpg --fingerprint <keyid>
# Compare fingerprint to the one as senders
################################################
# Singing the key as trustworthy
# edit key required
gpg --edit-key <keyid>
# new prompt will open gpg>
fpr # recheck fingerprint
sign # Will produce prompt for validation and password.
# Check all the signatures of a given key (in edit mode: gpg>)
check
##################################################
# Final check and viewing of public key
# We need to open the key in edit mode
gpg --edit-key <keyidentifier>
# The public key is displayed
# A message about the availability of a private key is displayed
# We can switch between public and private with:
toggle
# ENCRYPTING
#
# Requirements:
# <input_file> : Needs to be present
# <KeyID> : Public key of the recipient, needs to be already imported.
#
# Useful options:
#
# * --batch : Option for batch process / no prompts
# * if --output omitted then output to STDOUT
gpg --output doc.gpg --recipient <keyID> <input_file>
#* We can call output whatever we like, extension isnt necessary.
#* alternative parameter --output or -o
# DECRYPTING
# Decrypting is done with our own private key.
# Requirement : We need to have a public/private key pair generated.
gpg --output <filename> --decrypt filename.gpg
########
# How to automatically pass password to gpg command line
echo "PASSPHRASE" | gpg --passphrase-fd 0 -r USER --encrypt FILENAME.TXT
# In case we get error that the key is not signed:
echo "PASSPHRASE" | gpg --passphrase-fd 0 --always-trust -r USER --encrypt FILENAME.TX
# or more advanced:
cat something_so_sign.xzy | gpg \
--passphrase-file "plaintext_passphrase.txt" \
--batch \
--pinentry-mode loopback \
-bsa
########
# How to get long keyid for a given key
gpg --list-keys --with-colon name@domain.tld
########
# How to force add others public key to trusted keys
# First list all keys:
gpg --list-keys --with-colon name@domain.tld
#Add trusted key line to ~/gnupg/gpg.conf
trusted-key 16DIGITALPHANUMERICKEYID
#gpg line in backup script:
gpg -e -r name@domain.tld backup_file.tgz
######################################################
# A. ERROR TYPE: UNWANTED PROMPT
# echo "PASSPHRASE" | gpg --passphrase-fd 0 -r USER --encrypt FILENAME.TXT
# Error text:
#gpg: C042XXXX: There is no assurance this key belongs to the named user
#pub 40XXX/C042XXXX 2012-01-11 Name LastName. (comment) <user@email.com>
# Primary key fingerprint: XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX
# Subkey fingerprint: XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX
#It is NOT certain that the key belongs to the person named
#in the user ID. If you *really* know what you are doing,
#you may answer the next question with yes.
#
#Use this key anyway? (y/N)
# Fixes:
#1. Here is my solution, based on gpg2 (but I bet you can apply similar technique to gpg)
#$ gpg2 --edit-key {recipient email address}
#> trust
#> 5 (select 5 if you ultimately trust the key)
#> save
#This will tell gpg2 to trust the key fully, so that you can encrypt without prompt
####
#2. The hack approach:
#echo -n PASSPHRASE > phrase
#chmod 400 phrase #Make sure ONLY the user running the cron job can read the phrase
#yes | gpg --passphrase-fd 3 --recipient USER --encrypt FILENAME.txt 3<phrase
#The underlying problem is that the key you have forthe USER isnt signed. If you
#trust it, you can sign it with
gpg --edit-key USER sign
####
# 3. Using --always-trust
echo "PASSPHRASE" | gpg --passphrase-fd 0 --always-trust -r USER --encrypt FILENAME.TX
####
cat something_so_sign.xzy | gpg \
--passphrase-file "plaintext_passphrase.txt" \
--batch \
--pinentry-mode loopback \
-bsa
#####
I was running into this too. I couldn't get sign-key to do anything interesting. Here's what I did:
create a gpg key:
gpg --gen-key
get long key ID (result is in 5th column):
gpg --list-keys --with-colon name@domain.tld
Add trusted key line to ~/gnupg/gpg.conf
trusted-key 16DIGITALPHANUMERICKEYID
gpg line in backup script:
gpg -e -r name@domain.tld backup_file.tgz
Debugging cron: I'm also capturing cron dubugging output by sending stdout and stderr to a log file in the cron command line. It's helpful to know
shareeditflag
answered Jun 15 '15 at 20:33
jorfus
1,1681116
1
No, don't do that. Adding a trusted-key line to gpg.conf will cause gpg to always trust that key as fully as one of the user's own keys, which is a bad thing. Passing --trusted-key as an argument, and only in this specific case is acceptable (as is passing --trust-model=always in the same way). – Blacklight Shining Dec 13 '15 at 20:46
######
Or sign the key (after you veryfied the fingerprint, of course):
gpg --sign-key <recipient email address>
After that you fully trust the key.
1 = I don't know or won't say
2 = I do NOT trust
3 = I trust marginally
4 = I trust fully
5 = I trust ultimately
#######################################################
PRE-SCRIPT JOBS
1. Generate new key-pair
gpg --gen-key
RSA/RSA
2048?
Validity? Poso 0 for not expire
Associate with user
+ password
2. Generate revocation certificate for key
gpg --output revoke.asc --gen-revoke [mykey]
[mykey] = Key Specifier
3. List keys to check we have generated key-pair
gpg --list-keys
4. Export public key from our key chain
binary
gpg --output alice.gpg --export alice@cyb.org
ascii
gpg --output alice.asc --armor --export alice@cyb.org
5. Importing public key ( Key will be in form filename.gpg or filename.asc )
gpg --import blake.gpg
Check for succesful import:
gpg --list-keys
6. Validation of imported key with DIAS (Key needs to be signed as trustworthy)
gpg --fingerprint KeySpecifier
* Check if the produced fingerprint(hexadecimal) is the same as DIAS
7. Signing of key as Trustworthy
* Edit key required
gpg --edit-key KeySpecifier
fpr (* Recheck fingerprint)
* Signing
sign ( Will produce prompt for validation + password)
8. Check all signatures of the key
( In edit mode: check )
9. Final check view key
* We can simply view key by editting it
gpg --edit-key chloe@cyb.org
* The public key is displayed + Message about availability of private
* Switch between public / private with :
toggle
###################################################################
ENCRYPTING
* --batch : Option for batch process / no prompts
* if --output omitted then output to STDOUT
gpg --output doc.gpg --recipient <keyID> <input_file>
DECRYPTING
gpg --output <filename> --decrypt filename.gpg
####################################################################
GPG(1) GNU Privacy Guard GPG(1)
NAME
gpg - OpenPGP encryption and signing tool
SYNOPSIS
gpg [--homedir dir] [--options file] [options] command [args]
DESCRIPTION
gpg is the OpenPGP part of the GNU Privacy Guard (GnuPG). It is a tool to provide digital
encryption and signing services using the OpenPGP standard. gpg features complete key management
and all bells and whistles you can expect from a decent OpenPGP implementation.
This is the standalone version of gpg. For desktop use you should consider using gpg2 ([On
some platforms gpg2 is installed under the name gpg]).
RETURN VALUE
The program returns 0 if everything was fine, 1 if at least a signature was bad, and other error
codes for fatal errors.
WARNINGS
Use a *good* password for your user account and a *good* passphrase to protect your secret key.
This passphrase is the weakest part of the whole system. Programs to do dictionary attacks on
your secret keyring are very easy to write and so you should protect your "~/.gnupg/" directory
very well.
Keep in mind that, if this program is used over a network (telnet), it is *very* easy to spy out
your passphrase!
If you are going to verify detached signatures, make sure that the program knows about it;
either give both filenames on the command line or use '-' to specify STDIN.
INTEROPERABILITY
GnuPG tries to be a very flexible implementation of the OpenPGP standard. In particular, GnuPG
implements many of the optional parts of the standard, such as the SHA-512 hash, and the ZLIB
and BZIP2 compression algorithms. It is important to be aware that not all OpenPGP programs
implement these optional algorithms and that by forcing their use via the --cipher-algo,
--digest-algo, --cert-digest-algo, or --compress-algo options in GnuPG, it is possible to create
a perfectly valid OpenPGP message, but one that cannot be read by the intended recipient.
There are dozens of variations of OpenPGP programs available, and each supports a slightly dif‐
ferent subset of these optional algorithms. For example, until recently, no (unhacked) version
of PGP supported the BLOWFISH cipher algorithm. A message using BLOWFISH simply could not be
read by a PGP user. By default, GnuPG uses the standard OpenPGP preferences system that will
always do the right thing and create messages that are usable by all recipients, regardless of
which OpenPGP program they use. Only override this safe default if you really know what you are
doing.
If you absolutely must override the safe default, or if the preferences on a given key are
invalid for some reason, you are far better off using the --pgp6, --pgp7, or --pgp8 options.
These options are safe as they do not force any particular algorithms in violation of OpenPGP,
but rather reduce the available algorithms to a "PGP-safe" list.
COMMANDS
Commands are not distinguished from options except for the fact that only one command is
allowed.
gpg may be run with no commands, in which case it will perform a reasonable action depending on
the type of file it is given as input (an encrypted message is decrypted, a signature is veri‐
fied, a file containing keys is listed).
Please remember that option as well as command parsing stops as soon as a non-option is encoun‐
tered, you can explicitly stop parsing by using the special option --.
Commands not specific to the function
--version
Print the program version and licensing information. Note that you cannot abbreviate
this command.
--help
-h Print a usage message summarizing the most useful command line options. Note that you
cannot abbreviate this command.
--warranty
Print warranty information.
--dump-options
Print a list of all available options and commands. Note that you cannot abbreviate this
command.
Commands to select the type of operation
--sign
-s Make a signature. This command may be combined with --encrypt (for a signed and encrypted
message), --symmetric (for a signed and symmetrically encrypted message), or --encrypt
and --symmetric together (for a signed message that may be decrypted via a secret key or
a passphrase). The key to be used for signing is chosen by default or can be set with
the --local-user and --default-key options.
--clearsign
Make a clear text signature. The content in a clear text signature is readable without
any special software. OpenPGP software is only needed to verify the signature. Clear
text signatures may modify end-of-line whitespace for platform independence and are not
intended to be reversible. The key to be used for signing is chosen by default or can be
set with the --local-user and --default-key options.
--detach-sign
-b Make a detached signature.
--encrypt
-e Encrypt data. This option may be combined with --sign (for a signed and encrypted mes‐
sage), --symmetric (for a message that may be decrypted via a secret key or a
passphrase), or --sign and --symmetric together (for a signed message that may be
decrypted via a secret key or a passphrase).
--symmetric
-c Encrypt with a symmetric cipher using a passphrase. The default symmetric cipher used is
CAST5, but may be chosen with the --cipher-algo option. This option may be combined with
--sign (for a signed and symmetrically encrypted message), --encrypt (for a message that
may be decrypted via a secret key or a passphrase), or --sign and --encrypt together (for
a signed message that may be decrypted via a secret key or a passphrase).
--store
Store only (make a simple RFC1991 literal data packet).
--decrypt
-d Decrypt the file given on the command line (or STDIN if no file is specified) and write
it to STDOUT (or the file specified with --output). If the decrypted file is signed, the
signature is also verified. This command differs from the default operation, as it never
writes to the filename which is included in the file and it rejects files which don't
begin with an encrypted message.
--verify
Assume that the first argument is a signed file or a detached signature and verify it
without generating any output. With no arguments, the signature packet is read from
STDIN. If only a sigfile is given, it may be a complete signature or a detached signa‐
ture, in which case the signed stuff is expected in a file without the ".sig" or ".asc"
extension. With more than 1 argument, the first should be a detached signature and the
remaining files are the signed stuff. To read the signed stuff from STDIN, use '-' as the
second filename. For security reasons a detached signature cannot read the signed mate‐
rial from STDIN without denoting it in the above way.
--multifile
This modifies certain other commands to accept multiple files for processing on the com‐
mand line or read from STDIN with each filename on a separate line. This allows for many
files to be processed at once. --multifile may currently be used along with --verify,
--encrypt, and --decrypt. Note that --multifile --verify may not be used with detached
signatures.
--verify-files
Identical to --multifile --verify.
--encrypt-files
Identical to --multifile --encrypt.
--decrypt-files
Identical to --multifile --decrypt.
--list-keys
-k
--list-public-keys
List all keys from the public keyrings, or just the keys given on the command line. -k
is slightly different from --list-keys in that it allows only for one argument and takes
the second argument as the keyring to search. This is for command line compatibility
with PGP 2 and has been removed in gpg2.
Avoid using the output of this command in scripts or other programs as it is likely to
change as GnuPG changes. See --with-colons for a machine-parseable key listing command
that is appropriate for use in scripts and other programs.
--list-secret-keys
-K List all keys from the secret keyrings, or just the ones given on the command line. A #
after the letters sec means that the secret key is not usable (for example, if it was
created via --export-secret-subkeys).
--list-sigs
Same as --list-keys, but the signatures are listed too.
For each signature listed, there are several flags in between the "sig" tag and keyid.
These flags give additional information about each signature. From left to right, they
are the numbers 1-3 for certificate check level (see --ask-cert-level), "L" for a local
or non-exportable signature (see --lsign-key), "R" for a nonRevocable signature (see the
--edit-key command "nrsign"), "P" for a signature that contains a policy URL (see --cert-
policy-url), "N" for a signature that contains a notation (see --cert-notation), "X" for
an eXpired signature (see --ask-cert-expire), and the numbers 1-9 or "T" for 10 and above
to indicate trust signature levels (see the --edit-key command "tsign").
--check-sigs
Same as --list-sigs, but the signatures are verified. Note that for performance reasons
the revocation status of a signing key is not shown.
The status of the verification is indicated by a flag directly following the "sig" tag
(and thus before the flags described above for --list-sigs). A "!" indicates that the
signature has been successfully verified, a "-" denotes a bad signature and a "%" is used
if an error occurred while checking the signature (e.g. a non supported algorithm).
--fingerprint
List all keys (or the specified ones) along with their fingerprints. This is the same
output as --list-keys but with the additional output of a line with the fingerprint. May
also be combined with --list-sigs or --check-sigs. If this command is given twice, the
fingerprints of all secondary keys are listed too.
--list-packets
List only the sequence of packets. This is mainly useful for debugging.
--card-edit
Present a menu to work with a smartcard. The subcommand "help" provides an overview on
available commands. For a detailed description, please see the Card HOWTO at
http://www.gnupg.org/documentation/howtos.html#GnuPG-cardHOWTO .
--card-status
Show the content of the smart card.
--change-pin
Present a menu to allow changing the PIN of a smartcard. This functionality is also
available as the subcommand "passwd" with the --card-edit command.
--delete-key name
Remove key from the public keyring. In batch mode either --yes is required or the key
must be specified by fingerprint. This is a safeguard against accidental deletion of mul‐
tiple keys.
--delete-secret-key name
Remove key from the secret and public keyring. In batch mode the key must be specified by
fingerprint.
--delete-secret-and-public-key name
Same as --delete-key, but if a secret key exists, it will be removed first. In batch mode
the key must be specified by fingerprint.
--export
Either export all keys from all keyrings (default keyrings and those registered via
option --keyring), or if at least one name is given, those of the given name. The new
keyring is written to STDOUT or to the file given with option --output. Use together with
--armor to mail those keys.
--send-keys key IDs
Similar to --export but sends the keys to a keyserver. Fingerprints may be used instead
of key IDs. Option --keyserver must be used to give the name of this keyserver. Don't
send your complete keyring to a keyserver --- select only those keys which are new or
changed by you. If no key IDs are given, gpg does nothing.
--export-secret-keys
--export-secret-subkeys
Same as --export, but exports the secret keys instead. This is normally not very useful
and a security risk. The second form of the command has the special property to render
the secret part of the primary key useless; this is a GNU extension to OpenPGP and other
implementations can not be expected to successfully import such a key. See the option
--simple-sk-checksum if you want to import such an exported key with an older OpenPGP
implementation.
--import
--fast-import
Import/merge keys. This adds the given keys to the keyring. The fast version is currently
just a synonym.
There are a few other options which control how this command works. Most notable here is
the --import-options merge-only option which does not insert new keys but does only the
merging of new signatures, user-IDs and subkeys.
--recv-keys key IDs
Import the keys with the given key IDs from a keyserver. Option --keyserver must be used
to give the name of this keyserver.
--refresh-keys
Request updates from a keyserver for keys that already exist on the local keyring. This
is useful for updating a key with the latest signatures, user IDs, etc. Calling this with
no arguments will refresh the entire keyring. Option --keyserver must be used to give the
name of the keyserver for all keys that do not have preferred keyservers set (see --key‐
server-options honor-keyserver-url).
--search-keys names
Search the keyserver for the given names. Multiple names given here will be joined
together to create the search string for the keyserver. Option --keyserver must be used
to give the name of this keyserver. Keyservers that support different search methods
allow using the syntax specified in "How to specify a user ID" below. Note that different
keyserver types support different search methods. Currently only LDAP supports them all.
--fetch-keys URIs
Retrieve keys located at the specified URIs. Note that different installations of GnuPG
may support different protocols (HTTP, FTP, LDAP, etc.)
--update-trustdb
Do trust database maintenance. This command iterates over all keys and builds the Web of
Trust. This is an interactive command because it may have to ask for the "ownertrust"
values for keys. The user has to give an estimation of how far she trusts the owner of
the displayed key to correctly certify (sign) other keys. GnuPG only asks for the own‐
ertrust value if it has not yet been assigned to a key. Using the --edit-key menu, the
assigned value can be changed at any time.
--check-trustdb
Do trust database maintenance without user interaction. From time to time the trust data‐
base must be updated so that expired keys or signatures and the resulting changes in the
Web of Trust can be tracked. Normally, GnuPG will calculate when this is required and do
it automatically unless --no-auto-check-trustdb is set. This command can be used to force
a trust database check at any time. The processing is identical to that of --update-
trustdb but it skips keys with a not yet defined "ownertrust".
For use with cron jobs, this command can be used together with --batch in which case the
trust database check is done only if a check is needed. To force a run even in batch mode
add the option --yes.
--export-ownertrust
Send the ownertrust values to STDOUT. This is useful for backup purposes as these values
are the only ones which can't be re-created from a corrupted trustdb. Example:
gpg --export-ownertrust > otrust.txt
--import-ownertrust
Update the trustdb with the ownertrust values stored in files (or STDIN if not given);
existing values will be overwritten. In case of a severely damaged trustdb and if you
have a recent backup of the ownertrust values (e.g. in the file ‘otrust.txt’, you may re-
create the trustdb using these commands:
cd ~/.gnupg
rm trustdb.gpg
gpg --import-ownertrust < otrust.txt
--rebuild-keydb-caches
When updating from version 1.0.6 to 1.0.7 this command should be used to create signature
caches in the keyring. It might be handy in other situations too.
--print-md algo
--print-mds
Print message digest of algorithm ALGO for all given files or STDIN. With the second
form (or a deprecated "*" as algo) digests for all available algorithms are printed.
--gen-random 0|1|2 count
Emit count random bytes of the given quality level 0, 1 or 2. If count is not given or
zero, an endless sequence of random bytes will be emitted. If used with --armor the out‐
put will be base64 encoded. PLEASE, don't use this command unless you know what you are
doing; it may remove precious entropy from the system!
--gen-prime mode bits
Use the source, Luke :-). The output format is still subject to change.
--enarmor
--dearmor
Pack or unpack an arbitrary input into/from an OpenPGP ASCII armor. This is a GnuPG
extension to OpenPGP and in general not very useful.
How to manage your keys
This section explains the main commands for key management
--gen-key
Generate a new key pair. This command is normally only used interactively.
There is an experimental feature which allows you to create keys in batch mode. See the
file ‘doc/DETAILS’ in the source distribution on how to use this.
--gen-revoke name
Generate a revocation certificate for the complete key. To revoke a subkey or a signa‐
ture, use the --edit command.
--desig-revoke name
Generate a designated revocation certificate for a key. This allows a user (with the per‐
mission of the keyholder) to revoke someone else's key.
--edit-key
Present a menu which enables you to do most of the key management related tasks. It
expects the specification of a key on the command line.
uid n Toggle selection of user ID or photographic user ID with index n. Use * to select
all and 0 to deselect all.
key n Toggle selection of subkey with index n. Use * to select all and 0 to deselect
all.
sign Make a signature on key of user name If the key is not yet signed by the default
user (or the users given with -u), the program displays the information of the key
again, together with its fingerprint and asks whether it should be signed. This
question is repeated for all users specified with -u.
lsign Same as "sign" but the signature is marked as non-exportable and will therefore
never be used by others. This may be used to make keys valid only in the local
environment.
nrsign Same as "sign" but the signature is marked as non-revocable and can therefore
never be revoked.
tsign Make a trust signature. This is a signature that combines the notions of certifi‐
cation (like a regular signature), and trust (like the "trust" command). It is
generally only useful in distinct communities or groups.
Note that "l" (for local / non-exportable), "nr" (for non-revocable, and "t" (for trust)
may be freely mixed and prefixed to "sign" to create a signature of any type desired.
delsig Delete a signature. Note that it is not possible to retract a signature, once it
has been send to the public (i.e. to a keyserver). In that case you better use
revsig.
revsig Revoke a signature. For every signature which has been generated by one of the
secret keys, GnuPG asks whether a revocation certificate should be generated.
check Check the signatures on all selected user IDs.
adduid Create an additional user ID.
addphoto
Create a photographic user ID. This will prompt for a JPEG file that will be
embedded into the user ID. Note that a very large JPEG will make for a very large
key. Also note that some programs will display your JPEG unchanged (GnuPG), and
some programs will scale it to fit in a dialog box (PGP).
showphoto
Display the selected photographic user ID.
deluid Delete a user ID or photographic user ID. Note that it is not possible to retract
a user id, once it has been send to the public (i.e. to a keyserver). In that
case you better use revuid.
revuid Revoke a user ID or photographic user ID.
primary
Flag the current user id as the primary one, removes the primary user id flag from
all other user ids and sets the timestamp of all affected self-signatures one sec‐
ond ahead. Note that setting a photo user ID as primary makes it primary over
other photo user IDs, and setting a regular user ID as primary makes it primary
over other regular user IDs.
keyserver
Set a preferred keyserver for the specified user ID(s). This allows other users to
know where you prefer they get your key from. See --keyserver-options honor-key‐
server-url for more on how this works. Setting a value of "none" removes an
existing preferred keyserver.
notation
Set a name=value notation for the specified user ID(s). See --cert-notation for
more on how this works. Setting a value of "none" removes all notations, setting a
notation prefixed with a minus sign (-) removes that notation, and setting a nota‐
tion name (without the =value) prefixed with a minus sign removes all notations
with that name.
pref List preferences from the selected user ID. This shows the actual preferences,
without including any implied preferences.
showpref
More verbose preferences listing for the selected user ID. This shows the prefer‐
ences in effect by including the implied preferences of 3DES (cipher), SHA-1
(digest), and Uncompressed (compression) if they are not already included in the
preference list. In addition, the preferred keyserver and signature notations (if
any) are shown.
setpref string
Set the list of user ID preferences to string for all (or just the selected) user
IDs. Calling setpref with no arguments sets the preference list to the default
(either built-in or set via --default-preference-list), and calling setpref with
"none" as the argument sets an empty preference list. Use gpg --version to get a
list of available algorithms. Note that while you can change the preferences on an
attribute user ID (aka "photo ID"), GnuPG does not select keys via attribute user
IDs so these preferences will not be used by GnuPG.
When setting preferences, you should list the algorithms in the order which you'd
like to see them used by someone else when encrypting a message to your key. If
you don't include 3DES, it will be automatically added at the end. Note that
there are many factors that go into choosing an algorithm (for example, your key
may not be the only recipient), and so the remote OpenPGP application being used
to send to you may or may not follow your exact chosen order for a given message.
It will, however, only choose an algorithm that is present on the preference list
of every recipient key. See also the INTEROPERABILITY WITH OTHER OPENPGP PROGRAMS
section below.
addkey Add a subkey to this key.
addcardkey
Generate a subkey on a card and add it to this key.
keytocard
Transfer the selected secret subkey (or the primary key if no subkey has been
selected) to a smartcard. The secret key in the keyring will be replaced by a stub
if the key could be stored successfully on the card and you use the save command
later. Only certain key types may be transferred to the card. A sub menu allows
you to select on what card to store the key. Note that it is not possible to get
that key back from the card - if the card gets broken your secret key will be lost
unless you have a backup somewhere.
bkuptocard file
Restore the given file to a card. This command may be used to restore a backup key
(as generated during card initialization) to a new card. In almost all cases this
will be the encryption key. You should use this command only with the correspond‐
ing public key and make sure that the file given as argument is indeed the backup
to restore. You should then select 2 to restore as encryption key. You will first
be asked to enter the passphrase of the backup key and then for the Admin PIN of
the card.
delkey Remove a subkey (secondart key). Note that it is not possible to retract a subkey,
once it has been send to the public (i.e. to a keyserver). In that case you bet‐
ter use revkey.
revkey Revoke a subkey.
expire Change the key or subkey expiration time. If a subkey is selected, the expiration
time of this subkey will be changed. With no selection, the key expiration of the
primary key is changed.
trust Change the owner trust value for the key. This updates the trust-db immediately
and no save is required.
disable
enable Disable or enable an entire key. A disabled key can not normally be used for
encryption.
addrevoker
Add a designated revoker to the key. This takes one optional argument: "sensi‐
tive". If a designated revoker is marked as sensitive, it will not be exported by
default (see export-options).
passwd Change the passphrase of the secret key.
toggle Toggle between public and secret key listing.
clean Compact (by removing all signatures except the selfsig) any user ID that is no
longer usable (e.g. revoked, or expired). Then, remove any signatures that are not
usable by the trust calculations. Specifically, this removes any signature that
does not validate, any signature that is superseded by a later signature, revoked
signatures, and signatures issued by keys that are not present on the keyring.
minimize
Make the key as small as possible. This removes all signatures from each user ID
except for the most recent self-signature.
cross-certify
Add cross-certification signatures to signing subkeys that may not currently have
them. Cross-certification signatures protect against a subtle attack against sign‐
ing subkeys. See --require-cross-certification. All new keys generated have this
signature by default, so this option is only useful to bring older keys up to
date.
save Save all changes to the key rings and quit.
quit Quit the program without updating the key rings.
The listing shows you the key with its secondary keys and all user ids. The primary user
id is indicated by a dot, and selected keys or user ids are indicated by an asterisk.
The trust value is displayed with the primary key: the first is the assigned owner trust
and the second is the calculated trust value. Letters are used for the values:
- No ownertrust assigned / not yet calculated.
e Trust calculation has failed; probably due to an expired key.
q Not enough information for calculation.
n Never trust this key.
m Marginally trusted.
f Fully trusted.
u Ultimately trusted.
--sign-key name
Signs a public key with your secret key. This is a shortcut version of the subcommand
"sign" from --edit.
--lsign-key name
Signs a public key with your secret key but marks it as non-exportable. This is a short‐
cut version of the subcommand "lsign" from --edit-key.
OPTIONS
gpg features a bunch of options to control the exact behaviour and to change the default config‐
uration.
Long options can be put in an options file (default "~/.gnupg/gpg.conf"). Short option names
will not work - for example, "armor" is a valid option for the options file, while "a" is not.
Do not write the 2 dashes, but simply the name of the option and any required arguments. Lines
with a hash ('#') as the first non-white-space character are ignored. Commands may be put in
this file too, but that is not generally useful as the command will execute automatically with
every execution of gpg.
Please remember that option parsing stops as soon as a non-option is encountered, you can
explicitly stop parsing by using the special option --.
How to change the configuration
These options are used to change the configuration and are usually found in the option file.
--default-key name
Use name as the default key to sign with. If this option is not used, the default key is
the first key found in the secret keyring. Note that -u or --local-user overrides this
option.
--default-recipient name
Use name as default recipient if option --recipient is not used and don't ask if this is
a valid one. name must be non-empty.
--default-recipient-self
Use the default key as default recipient if option --recipient is not used and don't ask
if this is a valid one. The default key is the first one from the secret keyring or the
one set with --default-key.
--no-default-recipient
Reset --default-recipient and --default-recipient-self.
-v, --verbose
Give more information during processing. If used twice, the input data is listed in
detail.
--no-verbose
Reset verbose level to 0.
-q, --quiet
Try to be as quiet as possible.
--batch
--no-batch
Use batch mode. Never ask, do not allow interactive commands. --no-batch disables this
option. Note that even with a filename given on the command line, gpg might still need
to read from STDIN (in particular if gpg figures that the input is a detached signature
and no data file has been specified). Thus if you do not want to feed data via STDIN,
you should connect STDIN to ‘/dev/null’.
--no-tty
Make sure that the TTY (terminal) is never used for any output. This option is needed in
some cases because GnuPG sometimes prints warnings to the TTY even if --batch is used.
--yes Assume "yes" on most questions.
--no Assume "no" on most questions.
--list-options parameters
This is a space or comma delimited string that gives options used when listing keys and
signatures (that is, --list-keys, --list-sigs, --list-public-keys, --list-secret-keys,
and the --edit-key functions). Options can be prepended with a no- (after the two
dashes) to give the opposite meaning. The options are:
show-photos
Causes --list-keys, --list-sigs, --list-public-keys, and --list-secret-keys to
display any photo IDs attached to the key. Defaults to no. See also --photo-
viewer. Does not work with --with-colons: see --attribute-fd for the appropriate
way to get photo data for scripts and other frontends.
show-policy-urls
Show policy URLs in the --list-sigs or --check-sigs listings. Defaults to no.
show-notations
show-std-notations
show-user-notations
Show all, IETF standard, or user-defined signature notations in the --list-sigs or
--check-sigs listings. Defaults to no.
show-keyserver-urls
Show any preferred keyserver URL in the --list-sigs or --check-sigs listings.
Defaults to no.
show-uid-validity
Display the calculated validity of user IDs during key listings. Defaults to no.
show-unusable-uids
Show revoked and expired user IDs in key listings. Defaults to no.
show-unusable-subkeys
Show revoked and expired subkeys in key listings. Defaults to no.
show-keyring
Display the keyring name at the head of key listings to show which keyring a given
key resides on. Defaults to no.
show-sig-expire
Show signature expiration dates (if any) during --list-sigs or --check-sigs list‐
ings. Defaults to no.
show-sig-subpackets
Include signature subpackets in the key listing. This option can take an optional
argument list of the subpackets to list. If no argument is passed, list all sub‐
packets. Defaults to no. This option is only meaningful when using --with-colons
along with --list-sigs or --check-sigs.
--verify-options parameters
This is a space or comma delimited string that gives options used when verifying signa‐
tures. Options can be prepended with a `no-' to give the opposite meaning. The options
are:
show-photos
Display any photo IDs present on the key that issued the signature. Defaults to
no. See also --photo-viewer.
show-policy-urls
Show policy URLs in the signature being verified. Defaults to no.
show-notations
show-std-notations
show-user-notations
Show all, IETF standard, or user-defined signature notations in the signature
being verified. Defaults to IETF standard.
show-keyserver-urls
Show any preferred keyserver URL in the signature being verified. Defaults to no.
show-uid-validity
Display the calculated validity of the user IDs on the key that issued the signa‐
ture. Defaults to no.
show-unusable-uids
Show revoked and expired user IDs during signature verification. Defaults to no.
show-primary-uid-only
Show only the primary user ID during signature verification. That is all the AKA
lines as well as photo Ids are not shown with the signature verification status.
pka-lookups
Enable PKA lookups to verify sender addresses. Note that PKA is based on DNS, and
so enabling this option may disclose information on when and what signatures are
verified or to whom data is encrypted. This is similar to the "web bug" described
for the auto-key-retrieve feature.
pka-trust-increase
Raise the trust in a signature to full if the signature passes PKA validation.
This option is only meaningful if pka-lookups is set.
--enable-dsa2
--disable-dsa2
Enable hash truncation for all DSA keys even for old DSA Keys up to 1024 bit. This is
also the default with --openpgp. Note that older versions of GnuPG also required this
flag to allow the generation of DSA larger than 1024 bit.
--photo-viewer string
This is the command line that should be run to view a photo ID. "%i" will be expanded to
a filename containing the photo. "%I" does the same, except the file will not be deleted
once the viewer exits. Other flags are "%k" for the key ID, "%K" for the long key ID,
"%f" for the key fingerprint, "%t" for the extension of the image type (e.g. "jpg"), "%T"
for the MIME type of the image (e.g. "image/jpeg"), "%v" for the single-character calcu‐
lated validity of the image being viewed (e.g. "f"), "%V" for the calculated validity as
a string (e.g. "full"), and "%%" for an actual percent sign. If neither %i or %I are
present, then the photo will be supplied to the viewer on standard input.
The default viewer is "xloadimage -fork -quiet -title 'KeyID 0x%k' STDIN". Note that if
your image viewer program is not secure, then executing it from GnuPG does not make it
secure.
--exec-path string
Sets a list of directories to search for photo viewers and keyserver helpers. If not pro‐
vided, keyserver helpers use the compiled-in default directory, and photo viewers use the
$PATH environment variable. Note, that on W32 system this value is ignored when search‐
ing for keyserver helpers.
--keyring file
Add file to the current list of keyrings. If file begins with a tilde and a slash, these
are replaced by the $HOME directory. If the filename does not contain a slash, it is
assumed to be in the GnuPG home directory ("~/.gnupg" if --homedir or $GNUPGHOME is not
used).
Note that this adds a keyring to the current list. If the intent is to use the specified
keyring alone, use --keyring along with --no-default-keyring.
--secret-keyring file
Same as --keyring but for the secret keyrings.
--primary-keyring file
Designate file as the primary public keyring. This means that newly imported keys (via
--import or keyserver --recv-from) will go to this keyring.
--trustdb-name file
Use file instead of the default trustdb. If file begins with a tilde and a slash, these
are replaced by the $HOME directory. If the filename does not contain a slash, it is
assumed to be in the GnuPG home directory (‘~/.gnupg’ if --homedir or $GNUPGHOME is not
used).
--homedir dir
Set the name of the home directory to dir. If this option is not used, the home directory
defaults to ‘~/.gnupg’. It is only recognized when given on the command line. It also
overrides any home directory stated through the environment variable ‘GNUPGHOME’ or (on
W32 systems) by means of the Registry entry HKCU\Software\GNU\GnuPG:HomeDir.
--pcsc-driver file
Use file to access the smartcard reader. The current default is `libpcsclite.so.1' for
GLIBC based systems, `/System/Library/Frameworks/PCSC.framework/PCSC' for MAC OS X, `win‐
scard.dll' for Windows and `libpcsclite.so' for other systems.
--disable-ccid
Disable the integrated support for CCID compliant readers. This allows to fall back to
one of the other drivers even if the internal CCID driver can handle the reader. Note,
that CCID support is only available if libusb was available at build time.
--reader-port number_or_string
This option may be used to specify the port of the card terminal. A value of 0 refers to
the first serial device; add 32768 to access USB devices. The default is 32768 (first USB
device). PC/SC or CCID readers might need a string here; run the program in verbose mode
to get a list of available readers. The default is then the first reader found.
--display-charset name
Set the name of the native character set. This is used to convert some informational
strings like user IDs to the proper UTF-8 encoding. Note that this has nothing to do
with the character set of data to be encrypted or signed; GnuPG does not recode user-sup‐
plied data. If this option is not used, the default character set is determined from the
current locale. A verbosity level of 3 shows the chosen set. Valid values for name are:
iso-8859-1
This is the Latin 1 set.
iso-8859-2
The Latin 2 set.
iso-8859-15
This is currently an alias for the Latin 1 set.
koi8-r The usual Russian set (rfc1489).
utf-8 Bypass all translations and assume that the OS uses native UTF-8 encoding.
--utf8-strings
--no-utf8-strings
Assume that command line arguments are given as UTF8 strings. The default (--no-
utf8-strings) is to assume that arguments are encoded in the character set as specified
by --display-charset. These options affect all following arguments. Both options may be
used multiple times.
--options file
Read options from file and do not try to read them from the default options file in the
homedir (see --homedir). This option is ignored if used in an options file.
--no-options
Shortcut for --options /dev/null. This option is detected before an attempt to open an
option file. Using this option will also prevent the creation of a ‘~/.gnupg’ homedir.
-z n
--compress-level n
--bzip2-compress-level n
Set compression level to n for the ZIP and ZLIB compression algorithms. The default is to
use the default compression level of zlib (normally 6). --bzip2-compress-level sets the
compression level for the BZIP2 compression algorithm (defaulting to 6 as well). This is
a different option from --compress-level since BZIP2 uses a significant amount of memory
for each additional compression level. -z sets both. A value of 0 for n disables com‐
pression.
--bzip2-decompress-lowmem
Use a different decompression method for BZIP2 compressed files. This alternate method
uses a bit more than half the memory, but also runs at half the speed. This is useful
under extreme low memory circumstances when the file was originally compressed at a high
--bzip2-compress-level.
--mangle-dos-filenames
--no-mangle-dos-filenames
Older version of Windows cannot handle filenames with more than one dot. --mangle-dos-
filenames causes GnuPG to replace (rather than add to) the extension of an output file‐
name to avoid this problem. This option is off by default and has no effect on non-Win‐
dows platforms.
--ask-cert-level
--no-ask-cert-level
When making a key signature, prompt for a certification level. If this option is not
specified, the certification level used is set via --default-cert-level. See --default-
cert-level for information on the specific levels and how they are used. --no-ask-cert-
level disables this option. This option defaults to no.
--default-cert-level n
The default to use for the check level when signing a key.
0 means you make no particular claim as to how carefully you verified the key.
1 means you believe the key is owned by the person who claims to own it but you could
not, or did not verify the key at all. This is useful for a "persona" verification, where
you sign the key of a pseudonymous user.
2 means you did casual verification of the key. For example, this could mean that you
verified that the key fingerprint and checked the user ID on the key against a photo ID.
3 means you did extensive verification of the key. For example, this could mean that you
verified the key fingerprint with the owner of the key in person, and that you checked,
by means of a hard to forge document with a photo ID (such as a passport) that the name
of the key owner matches the name in the user ID on the key, and finally that you veri‐
fied (by exchange of email) that the email address on the key belongs to the key owner.
Note that the examples given above for levels 2 and 3 are just that: examples. In the
end, it is up to you to decide just what "casual" and "extensive" mean to you.
This option defaults to 0 (no particular claim).
--min-cert-level
When building the trust database, treat any signatures with a certification level below
this as invalid. Defaults to 2, which disregards level 1 signatures. Note that level 0
"no particular claim" signatures are always accepted.
--trusted-key long key ID
Assume that the specified key (which must be given as a full 8 byte key ID) is as trust‐
worthy as one of your own secret keys. This option is useful if you don't want to keep
your secret keys (or one of them) online but still want to be able to check the validity
of a given recipient's or signator's key.
--trust-model pgp|classic|direct|always|auto
Set what trust model GnuPG should follow. The models are:
pgp This is the Web of Trust combined with trust signatures as used in PGP 5.x and
later. This is the default trust model when creating a new trust database.
classic
This is the standard Web of Trust as used in PGP 2.x and earlier.
direct Key validity is set directly by the user and not calculated via the Web of Trust.
always Skip key validation and assume that used keys are always fully trusted. You gener‐
ally won't use this unless you are using some external validation scheme. This
option also suppresses the "[uncertain]" tag printed with signature checks when
there is no evidence that the user ID is bound to the key.
auto Select the trust model depending on whatever the internal trust database says.
This is the default model if such a database already exists.
--auto-key-locate parameters
--no-auto-key-locate
GnuPG can automatically locate and retrieve keys as needed using this option. This hap‐
pens when encrypting to an email address (in the "user@example.com" form), and there are
no user@example.com keys on the local keyring. This option takes any number of the fol‐
lowing mechanisms, in the order they are to be tried:
cert Locate a key using DNS CERT, as specified in rfc4398.
pka Locate a key using DNS PKA.
ldap Using DNS Service Discovery, check the domain in question for any LDAP keyservers
to use. If this fails, attempt to locate the key using the PGP Universal method
of checking 'ldap://keys.(thedomain)'.
keyserver
Locate a key using whatever keyserver is defined using the --keyserver option.
keyserver-URL
In addition, a keyserver URL as used in the --keyserver option may be used here to
query that particular keyserver.
local Locate the key using the local keyrings. This mechanism allows to select the
order a local key lookup is done. Thus using '--auto-key-locate local' is identi‐
cal to --no-auto-key-locate.
nodefault
This flag disables the standard local key lookup, done before any of the mecha‐
nisms defined by the --auto-key-locate are tried. The position of this mechanism
in the list does not matter. It is not required if local is also used.
--keyid-format short|0xshort|long|0xlong
Select how to display key IDs. "short" is the traditional 8-character key ID. "long" is
the more accurate (but less convenient) 16-character key ID. Add an "0x" to either to
include an "0x" at the beginning of the key ID, as in 0x99242560. Note that this option
is ignored if the option --with-colons is used.
--keyserver name
Use name as your keyserver. This is the server that --recv-keys, --send-keys, and
--search-keys will communicate with to receive keys from, send keys to, and search for
keys on. The format of the name is a URI: `scheme:[//]keyservername[:port]' The scheme is
the type of keyserver: "hkp" for the HTTP (or compatible) keyservers, "ldap" for the LDAP
keyservers, or "mailto" for the Graff email keyserver. Note that your particular instal‐
lation of GnuPG may have other keyserver types available as well. Keyserver schemes are
case-insensitive. After the keyserver name, optional keyserver configuration options may
be provided. These are the same as the global --keyserver-options from below, but apply
only to this particular keyserver.
Most keyservers synchronize with each other, so there is generally no need to send keys
to more than one server. The keyserver hkp://keys.gnupg.net uses round robin DNS to give
a different keyserver each time you use it.
--keyserver-options name=value1
This is a space or comma delimited string that gives options for the keyserver. Options
can be prefixed with a `no-' to give the opposite meaning. Valid import-options or
export-options may be used here as well to apply to importing (--recv-key) or exporting
(--send-key) a key from a keyserver. While not all options are available for all key‐
server types, some common options are:
include-revoked
When searching for a key with --search-keys, include keys that are marked on the
keyserver as revoked. Note that not all keyservers differentiate between revoked
and unrevoked keys, and for such keyservers this option is meaningless. Note also
that most keyservers do not have cryptographic verification of key revocations,
and so turning this option off may result in skipping keys that are incorrectly
marked as revoked.
include-disabled
When searching for a key with --search-keys, include keys that are marked on the
keyserver as disabled. Note that this option is not used with HKP keyservers.
auto-key-retrieve
This option enables the automatic retrieving of keys from a keyserver when verify‐
ing signatures made by keys that are not on the local keyring.
Note that this option makes a "web bug" like behavior possible. Keyserver opera‐
tors can see which keys you request, so by sending you a message signed by a brand
new key (which you naturally will not have on your local keyring), the operator
can tell both your IP address and the time when you verified the signature.
honor-keyserver-url
When using --refresh-keys, if the key in question has a preferred keyserver URL,
then use that preferred keyserver to refresh the key from. In addition, if auto-
key-retrieve is set, and the signature being verified has a preferred keyserver
URL, then use that preferred keyserver to fetch the key from. Defaults to yes.
honor-pka-record
If auto-key-retrieve is set, and the signature being verified has a PKA record,
then use the PKA information to fetch the key. Defaults to yes.
include-subkeys
When receiving a key, include subkeys as potential targets. Note that this option
is not used with HKP keyservers, as they do not support retrieving keys by subkey
id.
use-temp-files
On most Unix-like platforms, GnuPG communicates with the keyserver helper program
via pipes, which is the most efficient method. This option forces GnuPG to use
temporary files to communicate. On some platforms (such as Win32 and RISC OS),
this option is always enabled.
keep-temp-files
If using `use-temp-files', do not delete the temp files after using them. This
option is useful to learn the keyserver communication protocol by reading the tem‐
porary files.
verbose
Tell the keyserver helper program to be more verbose. This option can be repeated
multiple times to increase the verbosity level.
timeout
Tell the keyserver helper program how long (in seconds) to try and perform a key‐
server action before giving up. Note that performing multiple actions at the same
time uses this timeout value per action. For example, when retrieving multiple
keys via --recv-keys, the timeout applies separately to each key retrieval, and
not to the --recv-keys command as a whole. Defaults to 30 seconds.
http-proxy=value
Set the proxy to use for HTTP and HKP keyservers. This overrides the "http_proxy"
environment variable, if any.
max-cert-size
When retrieving a key via DNS CERT, only accept keys up to this size. Defaults to
16384 bytes.
debug Turn on debug output in the keyserver helper program. Note that the details of
debug output depends on which keyserver helper program is being used, and in turn,
on any libraries that the keyserver helper program uses internally (libcurl,
openldap, etc).
check-cert
Enable certificate checking if the keyserver presents one (for hkps or ldaps).
Defaults to on.
ca-cert-file
Provide a certificate store to override the system default. Only necessary if
check-cert is enabled, and the keyserver is using a certificate that is not
present in a system default certificate list.
Note that depending on the SSL library that the keyserver helper is built with,
this may actually be a directory or a file.
--completes-needed n
Number of completely trusted users to introduce a new key signer (defaults to 1).
--marginals-needed n
Number of marginally trusted users to introduce a new key signer (defaults to 3)
--max-cert-depth n
Maximum depth of a certification chain (default is 5).
--simple-sk-checksum
Secret keys are integrity protected by using a SHA-1 checksum. This method is part of the
upcoming enhanced OpenPGP specification but GnuPG already uses it as a countermeasure
against certain attacks. Old applications don't understand this new format, so this
option may be used to switch back to the old behaviour. Using this option bears a secu‐
rity risk. Note that using this option only takes effect when the secret key is encrypted
- the simplest way to make this happen is to change the passphrase on the key (even
changing it to the same value is acceptable).
--no-sig-cache
Do not cache the verification status of key signatures. Caching gives a much better per‐
formance in key listings. However, if you suspect that your public keyring is not save
against write modifications, you can use this option to disable the caching. It probably
does not make sense to disable it because all kind of damage can be done if someone else
has write access to your public keyring.
--no-sig-create-check
GnuPG normally verifies each signature right after creation to protect against bugs and
hardware malfunctions which could leak out bits from the secret key. This extra verifica‐
tion needs some time (about 115% for DSA keys), and so this option can be used to disable
it. However, due to the fact that the signature creation needs manual interaction, this
performance penalty does not matter in most settings.
--auto-check-trustdb
--no-auto-check-trustdb
If GnuPG feels that its information about the Web of Trust has to be updated, it automat‐
ically runs the --check-trustdb command internally. This may be a time consuming
process. --no-auto-check-trustdb disables this option.
--use-agent
--no-use-agent
Try to use the GnuPG-Agent. With this option, GnuPG first tries to connect to the agent
before it asks for a passphrase. --no-use-agent disables this option.
--gpg-agent-info
Override the value of the environment variable 'GPG_AGENT_INFO'. This is only used when
--use-agent has been given. Given that this option is not anymore used by gpg2, it
should be avoided if possible.
--lock-once
Lock the databases the first time a lock is requested and do not release the lock until
the process terminates.
--lock-multiple
Release the locks every time a lock is no longer needed. Use this to override a previous
--lock-once from a config file.
--lock-never
Disable locking entirely. This option should be used only in very special environments,
where it can be assured that only one process is accessing those files. A bootable floppy
with a stand-alone encryption system will probably use this. Improper usage of this
option may lead to data and key corruption.
--exit-on-status-write-error
This option will cause write errors on the status FD to immediately terminate the
process. That should in fact be the default but it never worked this way and thus we need
an option to enable this, so that the change won't break applications which close their
end of a status fd connected pipe too early. Using this option along with --enable-
progress-filter may be used to cleanly cancel long running gpg operations.
--limit-card-insert-tries n
With n greater than 0 the number of prompts asking to insert a smartcard gets limited to
N-1. Thus with a value of 1 gpg won't at all ask to insert a card if none has been
inserted at startup. This option is useful in the configuration file in case an applica‐
tion does not know about the smartcard support and waits ad infinitum for an inserted
card.
--no-random-seed-file
GnuPG uses a file to store its internal random pool over invocations. This makes random
generation faster; however sometimes write operations are not desired. This option can be
used to achieve that with the cost of slower random generation.
--no-greeting
Suppress the initial copyright message.
--no-secmem-warning
Suppress the warning about "using insecure memory".
--no-permission-warning
Suppress the warning about unsafe file and home directory (--homedir) permissions. Note
that the permission checks that GnuPG performs are not intended to be authoritative, but
rather they simply warn about certain common permission problems. Do not assume that the
lack of a warning means that your system is secure.
Note that the warning for unsafe --homedir permissions cannot be suppressed in the
gpg.conf file, as this would allow an attacker to place an unsafe gpg.conf file in place,
and use this file to suppress warnings about itself. The --homedir permissions warning
may only be suppressed on the command line.
--no-mdc-warning
Suppress the warning about missing MDC integrity protection.
--require-secmem
--no-require-secmem
Refuse to run if GnuPG cannot get secure memory. Defaults to no (i.e. run, but give a
warning).
--require-cross-certification
--no-require-cross-certification
When verifying a signature made from a subkey, ensure that the cross certification "back
signature" on the subkey is present and valid. This protects against a subtle attack
against subkeys that can sign. Defaults to --require-cross-certification for gpg.
--expert
--no-expert
Allow the user to do certain nonsensical or "silly" things like signing an expired or
revoked key, or certain potentially incompatible things like generating unusual key
types. This also disables certain warning messages about potentially incompatible
actions. As the name implies, this option is for experts only. If you don't fully under‐
stand the implications of what it allows you to do, leave this off. --no-expert disables
this option.
Key related options
--recipient name
-r Encrypt for user id name. If this option or --hidden-recipient is not specified, GnuPG
asks for the user-id unless --default-recipient is given.
--hidden-recipient name
-R Encrypt for user ID name, but hide the key ID of this user's key. This option helps to
hide the receiver of the message and is a limited countermeasure against traffic analy‐
sis. If this option or --recipient is not specified, GnuPG asks for the user ID unless
--default-recipient is given.
--encrypt-to name
Same as --recipient but this one is intended for use in the options file and may be used
with your own user-id as an "encrypt-to-self". These keys are only used when there are
other recipients given either by use of --recipient or by the asked user id. No trust
checking is performed for these user ids and even disabled keys can be used.
--hidden-encrypt-to name
Same as --hidden-recipient but this one is intended for use in the options file and may
be used with your own user-id as a hidden "encrypt-to-self". These keys are only used
when there are other recipients given either by use of --recipient or by the asked user
id. No trust checking is performed for these user ids and even disabled keys can be
used.
--no-encrypt-to
Disable the use of all --encrypt-to and --hidden-encrypt-to keys.
--group name=value1
Sets up a named group, which is similar to aliases in email programs. Any time the group
name is a recipient (-r or --recipient), it will be expanded to the values specified.
Multiple groups with the same name are automatically merged into a single group.
The values are key IDs or fingerprints, but any key description is accepted. Note that a
value with spaces in it will be treated as two different values. Note also there is only
one level of expansion --- you cannot make an group that points to another group. When
used from the command line, it may be necessary to quote the argument to this option to
prevent the shell from treating it as multiple arguments.
--ungroup name
Remove a given entry from the --group list.
--no-groups
Remove all entries from the --group list.
--local-user name
-u Use name as the key to sign with. Note that this option overrides --default-key.
--try-secret-key name
For hidden recipients GPG needs to know the keys to use for trial decryption. The key
set with --default-key is always tried first, but this is often not sufficient. This
option allows to set more keys to be used for trial decryption. Although any valid user-
id specification may be used for name it makes sense to use at least the long keyid to
avoid ambiguities. Note that gpg-agent might pop up a pinentry for a lot keys to do the
trial decryption. If you want to stop all further trial decryption you may use close-
window button instead of the cancel button.
--try-all-secrets
Don't look at the key ID as stored in the message but try all secret keys in turn to find
the right decryption key. This option forces the behaviour as used by anonymous recipi‐
ents (created by using --throw-keyids or --hidden-recipient) and might come handy in case
where an encrypted message contains a bogus key ID.
--skip-hidden-recipients
--no-skip-hidden-recipients
During decryption skip all anonymous recipients. This option helps in the case that peo‐
ple use the hidden recipients feature to hide there own encrypt-to key from others. If
oneself has many secret keys this may lead to a major annoyance because all keys are
tried in turn to decrypt soemthing which was not really intended for it. The drawback of
this option is that it is currently not possible to decrypt a message which includes real
anonymous recipients.
Input and Output
--armor
-a Create ASCII armored output. The default is to create the binary OpenPGP format.
--no-armor
Assume the input data is not in ASCII armored format.
--output file
-o file
Write output to file.
--max-output n
This option sets a limit on the number of bytes that will be generated when processing a
file. Since OpenPGP supports various levels of compression, it is possible that the
plaintext of a given message may be significantly larger than the original OpenPGP mes‐
sage. While GnuPG works properly with such messages, there is often a desire to set a
maximum file size that will be generated before processing is forced to stop by the OS
limits. Defaults to 0, which means "no limit".
--import-options parameters
This is a space or comma delimited string that gives options for importing keys. Options
can be prepended with a `no-' to give the opposite meaning. The options are:
import-local-sigs
Allow importing key signatures marked as "local". This is not generally useful
unless a shared keyring scheme is being used. Defaults to no.
repair-pks-subkey-bug
During import, attempt to repair the damage caused by the PKS keyserver bug (pre
version 0.9.6) that mangles keys with multiple subkeys. Note that this cannot com‐
pletely repair the damaged key as some crucial data is removed by the keyserver,
but it does at least give you back one subkey. Defaults to no for regular --import
and to yes for keyserver --recv-keys.
merge-only
During import, allow key updates to existing keys, but do not allow any new keys
to be imported. Defaults to no.
import-clean
After import, compact (remove all signatures except the self-signature) any user
IDs from the new key that are not usable. Then, remove any signatures from the
new key that are not usable. This includes signatures that were issued by keys
that are not present on the keyring. This option is the same as running the
--edit-key command "clean" after import. Defaults to no.
import-minimal
Import the smallest key possible. This removes all signatures except the most
recent self-signature on each user ID. This option is the same as running the
--edit-key command "minimize" after import. Defaults to no.
--export-options parameters
This is a space or comma delimited string that gives options for exporting keys. Options
can be prepended with a `no-' to give the opposite meaning. The options are:
export-local-sigs
Allow exporting key signatures marked as "local". This is not generally useful
unless a shared keyring scheme is being used. Defaults to no.
export-attributes
Include attribute user IDs (photo IDs) while exporting. This is useful to export
keys if they are going to be used by an OpenPGP program that does not accept
attribute user IDs. Defaults to yes.
export-sensitive-revkeys
Include designated revoker information that was marked as "sensitive". Defaults to
no.
export-reset-subkey-passwd
When using the --export-secret-subkeys command, this option resets the passphrases
for all exported subkeys to empty. This is useful when the exported subkey is to
be used on an unattended machine where a passphrase doesn't necessarily make
sense. Defaults to no.
export-clean
Compact (remove all signatures from) user IDs on the key being exported if the
user IDs are not usable. Also, do not export any signatures that are not usable.
This includes signatures that were issued by keys that are not present on the
keyring. This option is the same as running the --edit-key command "clean" before
export except that the local copy of the key is not modified. Defaults to no.
export-minimal
Export the smallest key possible. This removes all signatures except the most
recent self-signature on each user ID. This option is the same as running the
--edit-key command "minimize" before export except that the local copy of the key
is not modified. Defaults to no.
--with-colons
Print key listings delimited by colons. Note that the output will be encoded in UTF-8
regardless of any --display-charset setting. This format is useful when GnuPG is called
from scripts and other programs as it is easily machine parsed. The details of this for‐
mat are documented in the file ‘doc/DETAILS’, which is included in the GnuPG source dis‐
tribution.
--fixed-list-mode
Do not merge primary user ID and primary key in --with-colon listing mode and print all
timestamps as seconds since 1970-01-01.
--with-fingerprint
Same as the command --fingerprint but changes only the format of the output and may be
used together with another command.
--with-keygrip
Include the keygrip in the key listings.
OpenPGP protocol specific options.
-t, --textmode
--no-textmode
Treat input files as text and store them in the OpenPGP canonical text form with standard
"CRLF" line endings. This also sets the necessary flags to inform the recipient that the
encrypted or signed data is text and may need its line endings converted back to whatever
the local system uses. This option is useful when communicating between two platforms
that have different line ending conventions (UNIX-like to Mac, Mac to Windows, etc).
--no-textmode disables this option, and is the default.
If -t (but not --textmode) is used together with armoring and signing, this enables
clearsigned messages. This kludge is needed for command-line compatibility with command-
line versions of PGP; normally you would use --sign or --clearsign to select the type of
the signature.
--force-v3-sigs
--no-force-v3-sigs
OpenPGP states that an implementation should generate v4 signatures but PGP versions 5
through 7 only recognize v4 signatures on key material. This option forces v3 signatures
for signatures on data. Note that this option implies --no-ask-sig-expire, and unsets
--sig-policy-url, --sig-notation, and --sig-keyserver-url, as these features cannot be
used with v3 signatures. --no-force-v3-sigs disables this option. Defaults to no.
--force-v4-certs
--no-force-v4-certs
Always use v4 key signatures even on v3 keys. This option also changes the default hash
algorithm for v3 RSA keys from MD5 to SHA-1. --no-force-v4-certs disables this option.
--force-mdc
Force the use of encryption with a modification detection code. This is always used with
the newer ciphers (those with a blocksize greater than 64 bits), or if all of the recipi‐
ent keys indicate MDC support in their feature flags.
--disable-mdc
Disable the use of the modification detection code. Note that by using this option, the
encrypted message becomes vulnerable to a message modification attack.
--personal-cipher-preferences string
Set the list of personal cipher preferences to string. Use gpg --version to get a list
of available algorithms, and use none to set no preference at all. This allows the user
to safely override the algorithm chosen by the recipient key preferences, as GPG will
only select an algorithm that is usable by all recipients. The most highly ranked cipher
in this list is also used for the --symmetric encryption command.
--personal-digest-preferences string
Set the list of personal digest preferences to string. Use gpg --version to get a list
of available algorithms, and use none to set no preference at all. This allows the user
to safely override the algorithm chosen by the recipient key preferences, as GPG will
only select an algorithm that is usable by all recipients. The most highly ranked digest
algorithm in this list is also used when signing without encryption (e.g. --clearsign or
--sign).
--personal-compress-preferences string
Set the list of personal compression preferences to string. Use gpg --version to get a
list of available algorithms, and use none to set no preference at all. This allows the
user to safely override the algorithm chosen by the recipient key preferences, as GPG
will only select an algorithm that is usable by all recipients. The most highly ranked
compression algorithm in this list is also used when there are no recipient keys to con‐
sider (e.g. --symmetric).
--s2k-cipher-algo name
Use name as the cipher algorithm used to protect secret keys. The default cipher is
CAST5. This cipher is also used for conventional encryption if --personal-cipher-prefer‐
ences and --cipher-algo is not given.
--s2k-digest-algo name
Use name as the digest algorithm used to mangle the passphrases. The default algorithm
is SHA-1.
--s2k-mode n
Selects how passphrases are mangled. If n is 0 a plain passphrase (which is not recom‐
mended) will be used, a 1 adds a salt to the passphrase and a 3 (the default) iterates
the whole process a number of times (see --s2k-count). Unless --rfc1991 is used, this
mode is also used for conventional encryption.
--s2k-count n
Specify how many times the passphrase mangling is repeated. This value may range between
1024 and 65011712 inclusive. The default is inquired from gpg-agent. Note that not all
values in the 1024-65011712 range are legal and if an illegal value is selected, GnuPG
will round up to the nearest legal value. This option is only meaningful if --s2k-mode
is 3.
Compliance options
These options control what GnuPG is compliant to. Only one of these options may be active at a
time. Note that the default setting of this is nearly always the correct one. See the INTEROPER‐
ABILITY WITH OTHER OPENPGP PROGRAMS section below before using one of these options.
--gnupg
Use standard GnuPG behavior. This is essentially OpenPGP behavior (see --openpgp), but
with some additional workarounds for common compatibility problems in different versions
of PGP. This is the default option, so it is not generally needed, but it may be useful
to override a different compliance option in the gpg.conf file.
--openpgp
Reset all packet, cipher and digest options to strict OpenPGP behavior. Use this option
to reset all previous options like --s2k-*, --cipher-algo, --digest-algo and --compress-
algo to OpenPGP compliant values. All PGP workarounds are disabled.
--rfc4880
Reset all packet, cipher and digest options to strict RFC-4880 behavior. Note that this
is currently the same thing as --openpgp.
--rfc2440
Reset all packet, cipher and digest options to strict RFC-2440 behavior.
--rfc1991
Try to be more RFC-1991 (PGP 2.x) compliant.
--pgp2 Set up all options to be as PGP 2.x compliant as possible, and warn if an action is taken
(e.g. encrypting to a non-RSA key) that will create a message that PGP 2.x will not be
able to handle. Note that `PGP 2.x' here means `MIT PGP 2.6.2'. There are other versions
of PGP 2.x available, but the MIT release is a good common baseline.
This option implies --rfc1991 --disable-mdc --no-force-v4-certs --escape-from-lines
--force-v3-sigs --cipher-algo IDEA --digest-algo MD5 --compress-algo ZIP. It also dis‐
ables --textmode when encrypting.
--pgp6 Set up all options to be as PGP 6 compliant as possible. This restricts you to the
ciphers IDEA (if the IDEA plugin is installed), 3DES, and CAST5, the hashes MD5, SHA1 and
RIPEMD160, and the compression algorithms none and ZIP. This also disables --throw-
keyids, and making signatures with signing subkeys as PGP 6 does not understand signa‐
tures made by signing subkeys.
This option implies --disable-mdc --escape-from-lines --force-v3-sigs.
--pgp7 Set up all options to be as PGP 7 compliant as possible. This is identical to --pgp6
except that MDCs are not disabled, and the list of allowable ciphers is expanded to add
AES128, AES192, AES256, and TWOFISH.
--pgp8 Set up all options to be as PGP 8 compliant as possible. PGP 8 is a lot closer to the
OpenPGP standard than previous versions of PGP, so all this does is disable --throw-
keyids and set --escape-from-lines. All algorithms are allowed except for the SHA224,
SHA384, and SHA512 digests.
Doing things one usually doesn't want to do.
-n
--dry-run
Don't make any changes (this is not completely implemented).
--list-only
Changes the behaviour of some commands. This is like --dry-run but different in some
cases. The semantic of this command may be extended in the future. Currently it only
skips the actual decryption pass and therefore enables a fast listing of the encryption
keys.
-i
--interactive
Prompt before overwriting any files.
--debug-level level
Select the debug level for investigating problems. level may be a numeric value or by a
keyword:
none No debugging at all. A value of less than 1 may be used instead of the keyword.
basic Some basic debug messages. A value between 1 and 2 may be used instead of the
keyword.
advanced
More verbose debug messages. A value between 3 and 5 may be used instead of the
keyword.
expert Even more detailed messages. A value between 6 and 8 may be used instead of the
keyword.
guru All of the debug messages you can get. A value greater than 8 may be used instead
of the keyword. The creation of hash tracing files is only enabled if the keyword
is used.
How these messages are mapped to the actual debugging flags is not specified and may change with
newer releases of this program. They are however carefully selected to best aid in debugging.
--debug flags
Set debugging flags. All flags are or-ed and flags may be given in C syntax (e.g.
0x0042).
--debug-all
Set all useful debugging flags.
--debug-ccid-driver
Enable debug output from the included CCID driver for smartcards. Note that this option
is only available on some system.
--faked-system-time epoch
This option is only useful for testing; it sets the system time back or forth to epoch
which is the number of seconds elapsed since the year 1970. Alternatively epoch may be
given as a full ISO time string (e.g. "20070924T154812").
--enable-progress-filter
Enable certain PROGRESS status outputs. This option allows frontends to display a
progress indicator while gpg is processing larger files. There is a slight performance
overhead using it.
--status-fd n
Write special status strings to the file descriptor n. See the file DETAILS in the docu‐
mentation for a listing of them.
--status-file file
Same as --status-fd, except the status data is written to file file.
--logger-fd n
Write log output to file descriptor n and not to STDERR.
--log-file file
--logger-file file
Same as --logger-fd, except the logger data is written to file file. Note that --log-
file is only implemented for GnuPG-2.
--attribute-fd n
Write attribute subpackets to the file descriptor n. This is most useful for use with
--status-fd, since the status messages are needed to separate out the various subpackets
from the stream delivered to the file descriptor.
--attribute-file file
Same as --attribute-fd, except the attribute data is written to file file.
--comment string
--no-comments
Use string as a comment string in clear text signatures and ASCII armored messages or
keys (see --armor). The default behavior is not to use a comment string. --comment may be
repeated multiple times to get multiple comment strings. --no-comments removes all com‐
ments. It is a good idea to keep the length of a single comment below 60 characters to
avoid problems with mail programs wrapping such lines. Note that comment lines, like all
other header lines, are not protected by the signature.
--emit-version
--no-emit-version
Force inclusion of the version string in ASCII armored output. --no-emit-version dis‐
ables this option.
--sig-notation name=value
--cert-notation name=value
-N, --set-notation name=value
Put the name value pair into the signature as notation data. name must consist only of
printable characters or spaces, and must contain a '@' character in the form key‐
name@domain.example.com (substituting the appropriate keyname and domain name, of
course). This is to help prevent pollution of the IETF reserved notation namespace. The
--expert flag overrides the '@' check. value may be any printable string; it will be
encoded in UTF8, so you should check that your --display-charset is set correctly. If you
prefix name with an exclamation mark (!), the notation data will be flagged as critical
(rfc2440:5.2.3.15). --sig-notation sets a notation for data signatures. --cert-notation
sets a notation for key signatures (certifications). --set-notation sets both.
There are special codes that may be used in notation names. "%k" will be expanded into
the key ID of the key being signed, "%K" into the long key ID of the key being signed,
"%f" into the fingerprint of the key being signed, "%s" into the key ID of the key making
the signature, "%S" into the long key ID of the key making the signature, "%g" into the
fingerprint of the key making the signature (which might be a subkey), "%p" into the fin‐
gerprint of the primary key of the key making the signature, "%c" into the signature
count from the OpenPGP smartcard, and "%%" results in a single "%". %k, %K, and %f are
only meaningful when making a key signature (certification), and %c is only meaningful
when using the OpenPGP smartcard.
--sig-policy-url string
--cert-policy-url string
--set-policy-url string
Use string as a Policy URL for signatures (rfc2440:5.2.3.19). If you prefix it with an
exclamation mark (!), the policy URL packet will be flagged as critical. --sig-policy-url
sets a policy url for data signatures. --cert-policy-url sets a policy url for key signa‐
tures (certifications). --set-policy-url sets both.
The same %-expandos used for notation data are available here as well.
--sig-keyserver-url string
Use string as a preferred keyserver URL for data signatures. If you prefix it with an
exclamation mark (!), the keyserver URL packet will be flagged as critical.
The same %-expandos used for notation data are available here as well.
--set-filename string
Use string as the filename which is stored inside messages. This overrides the default,
which is to use the actual filename of the file being encrypted.
--for-your-eyes-only
--no-for-your-eyes-only
Set the `for your eyes only' flag in the message. This causes GnuPG to refuse to save the
file unless the --output option is given, and PGP to use a "secure viewer" with a claimed
Tempest-resistant font to display the message. This option overrides --set-filename.
--no-for-your-eyes-only disables this option.
--use-embedded-filename
--no-use-embedded-filename
Try to create a file with a name as embedded in the data. This can be a dangerous option
as it allows to overwrite files. Defaults to no.
--cipher-algo name
Use name as cipher algorithm. Running the program with the command --version yields a
list of supported algorithms. If this is not used the cipher algorithm is selected from
the preferences stored with the key. In general, you do not want to use this option as it
allows you to violate the OpenPGP standard. --personal-cipher-preferences is the safe
way to accomplish the same thing.
--digest-algo name
Use name as the message digest algorithm. Running the program with the command --version
yields a list of supported algorithms. In general, you do not want to use this option as
it allows you to violate the OpenPGP standard. --personal-digest-preferences is the safe
way to accomplish the same thing.
--compress-algo name
Use compression algorithm name. "zlib" is RFC-1950 ZLIB compression. "zip" is RFC-1951
ZIP compression which is used by PGP. "bzip2" is a more modern compression scheme that
can compress some things better than zip or zlib, but at the cost of more memory used
during compression and decompression. "uncompressed" or "none" disables compression. If
this option is not used, the default behavior is to examine the recipient key preferences
to see which algorithms the recipient supports. If all else fails, ZIP is used for maxi‐
mum compatibility.
ZLIB may give better compression results than ZIP, as the compression window size is not
limited to 8k. BZIP2 may give even better compression results than that, but will use a
significantly larger amount of memory while compressing and decompressing. This may be
significant in low memory situations. Note, however, that PGP (all versions) only sup‐
ports ZIP compression. Using any algorithm other than ZIP or "none" will make the message
unreadable with PGP. In general, you do not want to use this option as it allows you to
violate the OpenPGP standard. --personal-compress-preferences is the safe way to accom‐
plish the same thing.
--cert-digest-algo name
Use name as the message digest algorithm used when signing a key. Running the program
with the command --version yields a list of supported algorithms. Be aware that if you
choose an algorithm that GnuPG supports but other OpenPGP implementations do not, then
some users will not be able to use the key signatures you make, or quite possibly your
entire key.
--disable-cipher-algo name
Never allow the use of name as cipher algorithm. The given name will not be checked so
that a later loaded algorithm will still get disabled.
--disable-pubkey-algo name
Never allow the use of name as public key algorithm. The given name will not be checked
so that a later loaded algorithm will still get disabled.
--throw-keyids
--no-throw-keyids
Do not put the recipient key IDs into encrypted messages. This helps to hide the
receivers of the message and is a limited countermeasure against traffic analysis.
([Using a little social engineering anyone who is able to decrypt the message can check
whether one of the other recipients is the one he suspects.]) On the receiving side, it
may slow down the decryption process because all available secret keys must be tried.
--no-throw-keyids disables this option. This option is essentially the same as using
--hidden-recipient for all recipients.
--not-dash-escaped
This option changes the behavior of cleartext signatures so that they can be used for
patch files. You should not send such an armored file via email because all spaces and
line endings are hashed too. You can not use this option for data which has 5 dashes at
the beginning of a line, patch files don't have this. A special armor header line tells
GnuPG about this cleartext signature option.
--escape-from-lines
--no-escape-from-lines
Because some mailers change lines starting with "From " to ">From " it is good to handle
such lines in a special way when creating cleartext signatures to prevent the mail system
from breaking the signature. Note that all other PGP versions do it this way too.
Enabled by default. --no-escape-from-lines disables this option.
--passphrase-repeat n
Specify how many times gpg will request a new passphrase be repeated. This is useful for
helping memorize a passphrase. Defaults to 1 repetition.
--passphrase-fd n
Read the passphrase from file descriptor n. Only the first line will be read from file
descriptor n. If you use 0 for n, the passphrase will be read from STDIN. This can only
be used if only one passphrase is supplied.
--passphrase-file file
Read the passphrase from file file. Only the first line will be read from file file. This
can only be used if only one passphrase is supplied. Obviously, a passphrase stored in a
file is of questionable security if other users can read this file. Don't use this option
if you can avoid it.
--passphrase string
Use string as the passphrase. This can only be used if only one passphrase is supplied.
Obviously, this is of very questionable security on a multi-user system. Don't use this
option if you can avoid it.
--command-fd n
This is a replacement for the deprecated shared-memory IPC mode. If this option is
enabled, user input on questions is not expected from the TTY but from the given file
descriptor. It should be used together with --status-fd. See the file doc/DETAILS in the
source distribution for details on how to use it.
--command-file file
Same as --command-fd, except the commands are read out of file file
--allow-non-selfsigned-uid
--no-allow-non-selfsigned-uid
Allow the import and use of keys with user IDs which are not self-signed. This is not
recommended, as a non self-signed user ID is trivial to forge. --no-allow-non-selfsigned-
uid disables.
--allow-freeform-uid
Disable all checks on the form of the user ID while generating a new one. This option
should only be used in very special environments as it does not ensure the de-facto stan‐
dard format of user IDs.
--ignore-time-conflict
GnuPG normally checks that the timestamps associated with keys and signatures have plau‐
sible values. However, sometimes a signature seems to be older than the key due to clock
problems. This option makes these checks just a warning. See also --ignore-valid-from for
timestamp issues on subkeys.
--ignore-valid-from
GnuPG normally does not select and use subkeys created in the future. This option allows
the use of such keys and thus exhibits the pre-1.0.7 behaviour. You should not use this
option unless there is some clock problem. See also --ignore-time-conflict for timestamp
issues with signatures.
--ignore-crc-error
The ASCII armor used by OpenPGP is protected by a CRC checksum against transmission
errors. Occasionally the CRC gets mangled somewhere on the transmission channel but the
actual content (which is protected by the OpenPGP protocol anyway) is still okay. This
option allows GnuPG to ignore CRC errors.
--ignore-mdc-error
This option changes a MDC integrity protection failure into a warning. This can be use‐
ful if a message is partially corrupt, but it is necessary to get as much data as possi‐
ble out of the corrupt message. However, be aware that a MDC protection failure may also
mean that the message was tampered with intentionally by an attacker.
--no-default-keyring
Do not add the default keyrings to the list of keyrings. Note that GnuPG will not operate
without any keyrings, so if you use this option and do not provide alternate keyrings via
--keyring or --secret-keyring, then GnuPG will still use the default public or secret
keyrings.
--skip-verify
Skip the signature verification step. This may be used to make the decryption faster if
the signature verification is not needed.
--with-key-data
Print key listings delimited by colons (like --with-colons) and print the public key
data.
--fast-list-mode
Changes the output of the list commands to work faster; this is achieved by leaving some
parts empty. Some applications don't need the user ID and the trust information given in
the listings. By using this options they can get a faster listing. The exact behaviour of
this option may change in future versions. If you are missing some information, don't
use this option.
--no-literal
This is not for normal use. Use the source to see for what it might be useful.
--set-filesize
This is not for normal use. Use the source to see for what it might be useful.
--show-session-key
Display the session key used for one message. See --override-session-key for the counter‐
part of this option.
We think that Key Escrow is a Bad Thing; however the user should have the freedom to
decide whether to go to prison or to reveal the content of one specific message without
compromising all messages ever encrypted for one secret key. DON'T USE IT UNLESS YOU ARE
REALLY FORCED TO DO SO.
--override-session-key string
Don't use the public key but the session key string. The format of this string is the
same as the one printed by --show-session-key. This option is normally not used but comes
handy in case someone forces you to reveal the content of an encrypted message; using
this option you can do this without handing out the secret key.
--ask-sig-expire
--no-ask-sig-expire
When making a data signature, prompt for an expiration time. If this option is not speci‐
fied, the expiration time set via --default-sig-expire is used. --no-ask-sig-expire dis‐
ables this option.
--default-sig-expire
The default expiration time to use for signature expiration. Valid values are "0" for no
expiration, a number followed by the letter d (for days), w (for weeks), m (for months),
or y (for years) (for example "2m" for two months, or "5y" for five years), or an abso‐
lute date in the form YYYY-MM-DD. Defaults to "0".
--ask-cert-expire
--no-ask-cert-expire
When making a key signature, prompt for an expiration time. If this option is not speci‐
fied, the expiration time set via --default-cert-expire is used. --no-ask-cert-expire
disables this option.
--default-cert-expire
The default expiration time to use for key signature expiration. Valid values are "0"
for no expiration, a number followed by the letter d (for days), w (for weeks), m (for
months), or y (for years) (for example "2m" for two months, or "5y" for five years), or
an absolute date in the form YYYY-MM-DD. Defaults to "0".
--allow-secret-key-import
This is an obsolete option and is not used anywhere.
--allow-multiple-messages
--no-allow-multiple-messages
Allow processing of multiple OpenPGP messages contained in a single file or stream. Some
programs that call GPG are not prepared to deal with multiple messages being processed
together, so this option defaults to no. Note that versions of GPG prior to 1.4.7 always
allowed multiple messages.
Warning: Do not use this option unless you need it as a temporary workaround!
--enable-special-filenames
This options enables a mode in which filenames of the form ‘-&n’, where n is a non-nega‐
tive decimal number, refer to the file descriptor n and not to a file with that name.
--no-expensive-trust-checks
Experimental use only.
--preserve-permissions
Don't change the permissions of a secret keyring back to user read/write only. Use this
option only if you really know what you are doing.
--default-preference-list string
Set the list of default preferences to string. This preference list is used for new keys
and becomes the default for "setpref" in the edit menu.
--default-keyserver-url name
Set the default keyserver URL to name. This keyserver will be used as the keyserver URL
when writing a new self-signature on a key, which includes key generation and changing
preferences.
--list-config
Display various internal configuration parameters of GnuPG. This option is intended for
external programs that call GnuPG to perform tasks, and is thus not generally useful. See
the file ‘doc/DETAILS’ in the source distribution for the details of which configuration
items may be listed. --list-config is only usable with --with-colons set.
--gpgconf-list
This command is similar to --list-config but in general only internally used by the gpg‐
conf tool.
--gpgconf-test
This is more or less dummy action. However it parses the configuration file and returns
with failure if the configuration file would prevent gpg from startup. Thus it may be
used to run a syntax check on the configuration file.
Deprecated options
--load-extension name
Load an extension module. If name does not contain a slash it is searched for in the
directory configured when GnuPG was built (generally "/usr/local/lib/gnupg"). Extensions
are not generally useful anymore, and the use of this option is deprecated.
--show-photos
--no-show-photos
Causes --list-keys, --list-sigs, --list-public-keys, --list-secret-keys, and verifying a
signature to also display the photo ID attached to the key, if any. See also --photo-
viewer. These options are deprecated. Use --list-options [no-]show-photos and/or --ver‐
ify-options [no-]show-photos instead.
--show-keyring
Display the keyring name at the head of key listings to show which keyring a given key
resides on. This option is deprecated: use --list-options [no-]show-keyring instead.
--ctapi-driver file
Use file to access the smartcard reader. The current default is `libtowitoko.so'. Note
that the use of this interface is deprecated; it may be removed in future releases.
--always-trust
Identical to --trust-model always. This option is deprecated.
--show-notation
--no-show-notation
Show signature notations in the --list-sigs or --check-sigs listings as well as when ver‐
ifying a signature with a notation in it. These options are deprecated. Use --list-
options [no-]show-notation and/or --verify-options [no-]show-notation instead.
--show-policy-url
--no-show-policy-url
Show policy URLs in the --list-sigs or --check-sigs listings as well as when verifying a
signature with a policy URL in it. These options are deprecated. Use --list-options
[no-]show-policy-url and/or --verify-options [no-]show-policy-url instead.
EXAMPLES
gpg -se -r Bob file
sign and encrypt for user Bob
gpg --clearsign file
make a clear text signature
gpg -sb file
make a detached signature
gpg -u 0x12345678 -sb file
make a detached signature with the key 0x12345678
gpg --list-keys user_ID
show keys
gpg --fingerprint user_ID
show fingerprint
gpg --verify pgpfile
gpg --verify sigfile
Verify the signature of the file but do not output the data. The second form is used for
detached signatures, where sigfile is the detached signature (either ASCII armored or
binary) and are the signed data; if this is not given, the name of the file holding the
signed data is constructed by cutting off the extension (".asc" or ".sig") of sigfile or
by asking the user for the filename.
HOW TO SPECIFY A USER ID
There are different ways to specify a user ID to GnuPG. Some of them are only valid for gpg
others are only good for gpgsm. Here is the entire list of ways to specify a key:
By key Id.
This format is deduced from the length of the string and its content or 0x prefix. The
key Id of an X.509 certificate are the low 64 bits of its SHA-1 fingerprint. The use of
key Ids is just a shortcut, for all automated processing the fingerprint should be used.
When using gpg an exclamation mark (!) may be appended to force using the specified pri‐
mary or secondary key and not to try and calculate which primary or secondary key to use.
The last four lines of the example give the key ID in their long form as internally used
by the OpenPGP protocol. You can see the long key ID using the option --with-colons.
234567C4
0F34E556E
01347A56A
0xAB123456
234AABBCC34567C4
0F323456784E56EAB
01AB3FED1347A5612
0x234AABBCC34567C4
By fingerprint.
This format is deduced from the length of the string and its content or the 0x prefix.
Note, that only the 20 byte version fingerprint is available with gpgsm (i.e. the SHA-1
hash of the certificate).
When using gpg an exclamation mark (!) may be appended to force using the specified pri‐
mary or secondary key and not to try and calculate which primary or secondary key to use.
The best way to specify a key Id is by using the fingerprint. This avoids any ambigui‐
ties in case that there are duplicated key IDs.
1234343434343434C434343434343434
123434343434343C3434343434343734349A3434
0E12343434343434343434EAB3484343434343434
0xE12343434343434343434EAB3484343434343434
gpgsm also accepts colons between each pair of hexadecimal digits because this is the de-facto
standard on how to present X.509 fingerprints. gpg also allows the use of the space separated
SHA-1 fingerprint as printed by the key listing commands.
By exact match on OpenPGP user ID.
This is denoted by a leading equal sign. It does not make sense for X.509 certificates.
=Heinrich Heine <heinrichh@uni-duesseldorf.de>
By exact match on an email address.
This is indicated by enclosing the email address in the usual way with left and right
angles.
<heinrichh@uni-duesseldorf.de>
By word match.
All words must match exactly (not case sensitive) but can appear in any order in the user
ID or a subjects name. Words are any sequences of letters, digits, the underscore and
all characters with bit 7 set.
+Heinrich Heine duesseldorf
By exact match on the subject's DN.
This is indicated by a leading slash, directly followed by the RFC-2253 encoded DN of the
subject. Note that you can't use the string printed by "gpgsm --list-keys" because that
one as been reordered and modified for better readability; use --with-colons to print the
raw (but standard escaped) RFC-2253 string
/CN=Heinrich Heine,O=Poets,L=Paris,C=FR
By exact match on the issuer's DN.
This is indicated by a leading hash mark, directly followed by a slash and then directly
followed by the rfc2253 encoded DN of the issuer. This should return the Root cert of
the issuer. See note above.
#/CN=Root Cert,O=Poets,L=Paris,C=FR
By exact match on serial number and issuer's DN.
This is indicated by a hash mark, followed by the hexadecimal representation of the
serial number, then followed by a slash and the RFC-2253 encoded DN of the issuer. See
note above.
#4F03/CN=Root Cert,O=Poets,L=Paris,C=FR
By keygrip
This is indicated by an ampersand followed by the 40 hex digits of a keygrip. gpgsm
prints the keygrip when using the command --dump-cert. It does not yet work for OpenPGP
keys.
&D75F22C3F86E355877348498CDC92BD21010A480
By substring match.
This is the default mode but applications may want to explicitly indicate this by putting
the asterisk in front. Match is not case sensitive.
Heine
*Heine
Please note that we have reused the hash mark identifier which was used in old GnuPG versions to
indicate the so called local-id. It is not anymore used and there should be no conflict when
used with X.509 stuff.
Using the RFC-2253 format of DNs has the drawback that it is not possible to map them back to
the original encoding, however we don't have to do this because our key database stores this
encoding as meta data.
FILES
There are a few configuration files to control certain aspects of gpg's operation. Unless noted,
they are expected in the current home directory (see: [option --homedir]).
gpg.conf
This is the standard configuration file read by gpg on startup. It may contain any valid
long option; the leading two dashes may not be entered and the option may not be abbrevi‐
ated. This default name may be changed on the command line (see: [option --options]).
You should backup this file.
Note that on larger installations, it is useful to put predefined files into the directory
‘/etc/skel/.gnupg/’ so that newly created users start up with a working configuration.
For internal purposes gpg creates and maintains a few other files; They all live in in the cur‐
rent home directory (see: [option --homedir]). Only the gpg may modify these files.
~/.gnupg/secring.gpg
The secret keyring. You should backup this file.
~/.gnupg/secring.gpg.lock
The lock file for the secret keyring.
~/.gnupg/pubring.gpg
The public keyring. You should backup this file.
~/.gnupg/pubring.gpg.lock
The lock file for the public keyring.
~/.gnupg/trustdb.gpg
The trust database. There is no need to backup this file; it is better to backup the
ownertrust values (see: [option --export-ownertrust]).
~/.gnupg/trustdb.gpg.lock
The lock file for the trust database.
~/.gnupg/random_seed
A file used to preserve the state of the internal random pool.
/usr[/local]/share/gnupg/options.skel
The skeleton options file.
/usr[/local]/lib/gnupg/
Default location for extensions.
Operation is further controlled by a few environment variables:
HOME Used to locate the default home directory.
GNUPGHOME
If set directory used instead of "~/.gnupg".
GPG_AGENT_INFO
Used to locate the gpg-agent. This is only honored when --use-agent is set. The value
consists of 3 colon delimited fields: The first is the path to the Unix Domain Socket,
the second the PID of the gpg-agent and the protocol version which should be set to 1.
When starting the gpg-agent as described in its documentation, this variable is set to
the correct value. The option --gpg-agent-info can be used to override it.
PINENTRY_USER_DATA
This value is passed via gpg-agent to pinentry. It is useful to convey extra information
to a custom pinentry.
COLUMNS
LINES Used to size some displays to the full size of the screen.
LANGUAGE
Apart from its use by GNU, it is used in the W32 version to override the language selec‐
tion done through the Registry. If used and set to a valid and available language name
(langid), the file with the translation is loaded from
gpgdir/gnupg.nls/langid.mo. Here gpgdir is the directory out of which the gpg binary has
been loaded. If it can't be loaded the Registry is tried and as last resort the native
Windows locale system is used.
BUGS
On older systems this program should be installed as setuid(root). This is necessary to lock
memory pages. Locking memory pages prevents the operating system from writing memory pages
(which may contain passphrases or other sensitive material) to disk. If you get no warning mes‐
sage about insecure memory your operating system supports locking without being root. The pro‐
gram drops root privileges as soon as locked memory is allocated.
Note also that some systems (especially laptops) have the ability to ``suspend to disk'' (also
known as ``safe sleep'' or ``hibernate''). This writes all memory to disk before going into a
low power or even powered off mode. Unless measures are taken in the operating system to pro‐
tect the saved memory, passphrases or other sensitive material may be recoverable from it later.
Before you report a bug you should first search the mailing list archives for similar problems
and second check whether such a bug has already been reported to our bug tracker at
http://bugs.gnupg.org .
SEE ALSO
gpgv(1),
The full documentation for this tool is maintained as a Texinfo manual. If GnuPG and the info
program are properly installed at your site, the command
info gnupg
should give you access to the complete manual including a menu structure and an index.
GnuPG 1.4.12 2017-08-29 GPG(1)
####
# Basics
# Each time you use a symmetric cipher to encrypt data, you'll be asked to supply a passphrase (twice to confirm it).
# This passphrase is used to help generate a key which is then used with the chosen algorithm to encrypt the data.
# It goes without saying (but we'll say it anyway) that you should use a strong passphrase and don't forget what you chose!.
# When you get around to decrypting the data, you'll be prompted for that passphrase.
#ENCRYPTING / DECRYPTING (SYMMETRIC)
gpg --output doc.gpg --symmetric doc
gpg --output doc --symmetric dog.gpg
#* Prompt will be given for passphrase to gain access to private key.
####
# Check which cyphers are available by gpg
gpg --version
# Cypher: 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH, CAMELLIA128,
# CAMELLIA192, CAMELLIA256
####
# ENCRYPT USING DIFFERENT ALGORITHM ()
# Ex 1 - AES256
# This will yield a file.txt.gpg
gpg --symmetric --cipher-algo AES256 file.txt
# decrypt
gpg -o original_file.txt -d file.txt.gpg
# Ex 2 - Twofish (Blocksize = 128, Strong, In gpg works with 256 key by default)
gpg --symmetric --cipher-algo TWOFISH file.txt
# decrypt
gpg -d file.txt.gpg
# Ex 3 - Camellia256 (Blocksize = 128, Keysize = 256)
gpg --symmetric --cipher-algo CAMELLIA256 file.txt
#decrypt
gpg -d file.txt.gpg
# Ex 4 - CAST5 (Default GPG cipher)
#If you don't specify what algorithm to use then CAST5 will be used by default.
#CAST5 has a block size of 64 bits. This is a decent cipher which is considered
#safe to use by some, for example the Canadian government. However, many top
# cryptographers such as Bruce Schneier would recommend that its better to use
#a cipher with a bigger block size than 64 bits.
gpg --symmetric file.txt
#decrypt
gpg -d file.txt.gpg
# How to change default cipher
# if you wish to choose an even better algorithm such as Twofish or AES256 which
# both have a block size of 128bits, you can configure the default by editing
# ~/.gnupg/gpg.conf and adding a line like the one below, replacing "NAME" with the appropriate algorithm name from the above "Cypher" list:
cipher-algo NAME
# so to make AES256 your default, you would add the below line to ~/.gnupg/gpg.conf
cipher-algo AES256
# If you stick with CAST5 or any cipher with a block size less than or equal
# to 64bits (3DES is another example of a 64bit block size), you should also use
# the --force-mdc option. This forces "the use of encryption with a modification
# detection code". Without the use of an mdc, "the encrypted message becomes
# vulnerable to a message modification attack" according to the gpg man page.
# So just to be clear: for ciphers with block size 64bits or less, you will get
# the following warning when decrypting unless you use the --force-mdc option:
gpg: WARNING: message was not integrity protected
# You could add force-mdc to your ~/.gnupg/gpg.conf so you don't have to specify
# --force-mdc on the command line each time (--force-mdc behaviour is already
# being done for ciphers with larger block sizes, so it will just be ignored if
# used with them). Assuming you've not touched your defaults in ~/.gnupg/gpg.conf,
# to encrypt a file called file.txt using the CAST5 cipher you'll just need to
# use:
gpg --symmetric --force-mdc file.txt
# This will produce file.txt.gpg containing the encrypted data. As usual, you
# can call the resulting file whatever you like by using the -o (or --output) option.
#So to call it file.enc, you'd use:
gpg -o file.enc --symmetric --force-mdc file.txt
#Then to decrypt it you just need to use the -d option along with whatever your
#encrypted file is called (e.g. file.txt.gpg).
gpg -o original_file.txt -d file.txt.gpg
#Note that if you don't use -o to output to file, the decrypted data gets sent to
#standard out, which unless you redirect it to a file or pipe it to another program,
#will end up being displayed on your screen.
####
# USER FRIENDLY DATA
# If you need to copy and past your encrypted data (e.g. into an email), then use
#the --armor option. This will produce ascii armored text (base64 encoded) which
# is very portable. Taking AES256 as an example, you would simply use it like this:
gpg --armor --symmetric --cipher-algo AES256 file.txt
#By default, this will produce file.txt.asc as the encrypted ascii armored file. You would then decrypt normally using something like:
gpg -o file.txt -d file.txt.asc
##
# Digitally signing symmetrically encrypted data
#If you have set up a public/private key pair, you can use your private key to
#sign the data before symmetrically encrypting it.
#For information about how to create your own public/private key pair, see GPG Encryption Guide - Part 1.
#To learn more about digital signatures, see GPG Encryption Guide - Part 3.
#For example, to sign and symmetrically encrypt file.txt using AES256, use the --sign option like this:
gpg --sign --symmetric --cipher-algo AES256 file.txt
#Then to verify the signature and decrypt, you would use:
gpg -d file.txt.gpg
#(The -d option will automatically try to verify any signature and also decrypt).
Gnu Privacy Guard (GnuPG) Mini Howto (English)
Brenno J.S.A.A.F. de Winter (English) <brenno@dewinter.com>
Michael Fischer v. Mollard (German) <fischer@math.uni-goet
tingen.de> Arjen Baart <arjen@andromeda.nl>
Version 0.1.4 August 10, 2004
This documents explains how to use the GNU Privacy Guard (GnuPG), an
Open Source OpenPGP compatible encryption system To keep this program
totally free the use of the RSA algorithm and other patented algorithm
has been avoided. The document was originally written by Michael
Fischer v. Mollar in German. The text has been translated and
adjusted on some points and cannot be considered as a full one-on-
one copy.
______________________________________________________________________
Table of Contents
1. Concepts
1.1 Public Key Encryption
1.2 Digital Signatures
1.3 Web of trust
1.4 Boundaries to security
2. Installation
2.1 Sources for GnuPG.
2.2 Configuration
2.3 Compile
2.4 Installation
3. Using keys
3.1 Creating a key
3.2 Exporting keys
3.3 Importing keys
3.4 Revoke a key
3.5 Key administration
3.6 Key signing
4. Encrypt and decrypt
4.1 Encrypt
4.2 Decrypt
5. Signing and checking signatures
6. Front ends
6.1 Graphical interfaces
6.1.1 GPA
6.1.2 Seahorse
6.1.3 Geheimnis
6.2 Email programs
6.2.1 Mozilla and Enigmail
6.2.2 Evolution
6.2.3 Kmail
7. Sources of information
7.1 GnuPG
7.2 PGP
7.3 Keyservers
7.4 Books
8. About this document
8.1 Versions
______________________________________________________________________
11.. CCoonncceeppttss
11..11.. PPuubblliicc KKeeyy EEnnccrryyppttiioonn
Classic methods for encryption only use one key for encryption. The
sender encrypts the message with this key. To be able to decrypt this
the receiver needs to have this very same key. This key must have been
given to the receiver in a way, that others won't have had the
opportunity to obtain this key. If somebody else does have the key,
this method of encryption is useless.
The use of so-called Public Keys can solve this problem. Public Keys
is a concept where two keys are involved. One key is a Public Key that
can be spread through all sorts of media and may be obtained by
anyone. The other key is the Private Key. This key is secret and
cannot be spread. This key is only available to the owner. When the
system is well implemented the secret key cannot be derived from the
public key. Now the sender will crypt the message with the public key
belonging to the receiver. Then decryption will be done with the
secret key of the receiver.
Crucial in this concept is that the secret key remains a secret and
should not be given away or become available to anyone else but the
owner of this key. YOU CANNOT SEND THIS KEY OVER THE INTERNET. Also it
is very unwise to use GnuPG over telnet (you might consider never to
use telnet based on the high security risks).
11..22.. DDiiggiittaall SSiiggnnaattuurreess
In order to prove that a message was really sent by the alleged sender
the concept of Digital Signatures was invented. As the name says a
message is digitally signed by the sender. By using this signature you
can check the authenticity of a message. Using this will reduce the
risk for Trojan horses (a message that claims to be a patch to a
certain problem but actually contains a virus or does something bad
with data on your computer). Also information or data can be verified
as coming from a legitimate source and thus be regarded as real.
A digital signature is made through a combination of the secret key
and the text. Using the senders public key the message can be
verified. Not only will be checked if the correct sender is involved,
also the content will be checked. So you know that the message comes
from the sender and has not been changed during the transportation
process.
11..33.. WWeebb ooff ttrruusstt
A weak point of the Public key algorithms is the spreading of the
public keys. A user could bring a public key with false user ID in
circulation. If with this particular key messages are made, the
intruder can decode and read the messages. If the intruder passes it
on then still with a genuine public key coded to the actual recipient,
this attack is not noticeable.
The PGP solution (and because of that automatically the GnuPG
solution) exists in signing codes. A public key can be signed by other
people. This signature acknowledges that the key used by the UID (User
Identification) actually belongs to the person it claims to be. It is
then up to the user of GnuPG how far the trust in the signature goes.
You can consider a key as trustworthy when you trust the sender of the
key and you know for sure that the key really belongs to that person.
Only when you can trust the key of the signer, you can trust the
signature. To be absolutely positive that the key is correct you have
to compare the finger print over reliable channels before giving
absolute trust.
11..44.. BBoouunnddaarriieess ttoo sseeccuurriittyy
If you have data that you would like to remain confidential, there is
more to it than just determining which encoding algorithm to use. You
should be thinking about your system security in general. Basically we
consider PGP to be secure and as I write this documents no incidents
of PGP being cracked are known to me. But that doesn't mean that all
encoding must be safe then (for instance the NSA wouldn't notify me if
they cracked PGP somehow, neither would other people who crack for
real malicious grounds). But even if the PGP is fully 'unhackable',
other means can be used to attack the security. Early February 1999 a
Trojan Horse had been found that searched for secret PGP keys on the
hard disk and FTP-ed them away. If the password has been chosen badly
the secret key can easily be cracked.
Another technical possibility (although more difficult) is a Trojan
Horse that broadcasts keyboard entries. Also possible (but very
difficult) is to pass the content of a screen along. Then no cracking
of scrambled messages needs to be done. For all these risks there need
to be a good, well-thought security plan that is actually deployed.
It is not a goal to create paranoia among people, but to point out
that a lot needs to be done to be more secure. The most important
thing is to realize that encryption is just one step to security and
is not a total solution. Trojan horses as they appeared in the Melissa
virus in March 1999 proved that many companies are not prepared for
that.
22.. IInnssttaallllaattiioonn
22..11.. SSoouurrcceess ffoorr GGnnuuPPGG..
The official download site is: GnuPG Homepage
<http://www.gnupg.org/download.html>. At that location you will find
links to mirror sites.
Due to legal restrictions it is not allowed to download GnuPG from
servers based in the USA. The USA imposes export restrictions on the
export of cryptographic software. This is why PGP is always available
in an international and a national (for the USA) version. For the
international version the source code has been exported in a printed
format as a book. In Europe (Oslo) it has been scanned. More
information on that can be found on International PGP Homepage
<http://www.pgpi.com>. The international version of PGP is free to be
imported into the United States as long as it is not reexported again.
If you already have an installed version of GnuPG or PGP, you should
check the signature of the file (see ``Signatures'').
22..22.. CCoonnffiigguurraattiioonn
You can obtain GnuPG as a Debian Package, as a RPM package (Redhat
Package Manager) or in source code. GnuPG is included in the latest
Fedora/Redhat Linux distributions. To check if you have GnuPG
installed on your system, use:
rpm -q gnupg
The packages are installed as binary files with the tools needed for
Linux platforms. When you need GnuPG for different platforms you need
to compile this yourself. It would be appreciated when you make
alternative installation methods for different platforms available to
the general public.
Since development for the major part takes place with Linux (x86),
translation to different systems should not be regarded as being a
problem. The actual list of known operating systems that support GnuPG
can be found on GnuPG Homepage. The procedure as described below is
pretty platform independent. This procedure can be used to install
GnuPG out of a source code tar-ball.
Unpack the tar-ball with the following commands, For sources
compressed with gzip use:
tar xvzf gnupg-?.?.?.tar.gz
and for sources compressed with bzip2 use:
tar xvjf gnupg-?.?.?.tar.bz2
After the unpack, please step into the directory containing the source
code. Then type
./configure
When doing this nothing special should happen. With
./configure --help
you can view the available configuration settings for compilation. If
problems occur that have to do with internationalization (gettext),
you can include a version that is delivered with the source code by
using the option --with-included-gettext or switch it of by using the
--disable-NLS option.
22..33.. CCoommppiillee
After this we want to compile the stuff by typing:
make
This should work without any problems. If any problems occur take the
following steps (in the same order as described here): First try to
solve this yourself (of course also by using the available documenta
tion). Then make sure that your problem is not a known bug (check the
BUGS file on http://www.gnupg.org). Then ask someone you know. If
these steps do not solve your problem post a question to the GnuPG-
mailing list (see ``Informationsources''). If the problem is path
related, you should try make clean, then run configure again and retry
to compile. If that doesn't work it is time to panic.
22..44.. IInnssttaallllaattiioonn
Now type:
make install
to actually copy the program and the man-pages into the installation
directory. If you didn't change the installation directory when you
did ./configure the usr/local/share/gnupg/ will be the installation
directory. You can find this directory in the file options.skel. When
you change this options.skel. If you copy this to ~/.gnupg/options the
appropriate adjustments will be used as standard. Copying should occur
automatically when creating ~/.gnupg/. All possible options are well
documented and explaining them here would not be useful.
You can run GnuPG as suid root. So the program runs with all the
rights the superuser has. By doing this you exclude the possibility
that certain parts of the program are stored externally and then could
be read by anyone. It is not feasible for me to judge on the value of
this risk. But running the program as suid root one should be alert to
the danger of Trojan horses. Since a Trojan horse running as superuser
can damage an entire system. If for this reason (or any other reason)
you choose not run GnuPG as root you can switch off the warning by
setting no-secmem-warning in ~/.gnupg/options.
33.. UUssiinngg kkeeyyss
33..11.. CCrreeaattiinngg aa kkeeyy
With
gpg --gen-key
a new key-pair is created (key pair: secret and public key). The
first question is which algorithm can be used. You can read more about
algorithms in PGP DH vs. RSA FAQ <http://www.samsimpson.com/cryptogra
phy/pgp/pgpfaq.html> or in ``Applied Cryptography''. You can easily
(and maybe you should - since it is used so widely) use DSA/ ElGamal.
This is not patented.
The next question is key length. This is something that is very user
dependent. You need to choose between security and calculating time.
If a key is longer the risk for cracking the message when intercepted
decreases. But with a larger key calculation time also increases. If
computing time is an issue you still should consider that you want to
use the key for sometime. We all know that arithmetic performance
increases very quickly, since new processors are getting quicker and
quicker. So keep this in mind. The minimal key length GnuPG demands
is 768 bits. However some people say you should have at a key-size of
2048 bits (which is also really a maximum with GnuPG at this moment).
For DSA 1024 is a standard size. When security is a top priority and
performance is less an issue you ought to pick the largest key-size
available.
The system now asks to enter names, comment and e-mail address. Based
upon the entries here the code is calculated. You can change these
settings later. See ``Administering keypairs''.
Finally you have to enter a password (actually passphrase would be
more appropriate, since blanks are allowed). This password is used to
be able to use the functionality which belongs to your secret key. A
good passphrase contains the following elements:
· it is long,
· it has special (non alphanumeric) characters,
· it is something special (not a name),
· it is very hard to guess (so NOT names, birth dates, phone numbers,
number of a credit card/checking account, names and number of
children, ...)
By sometimes using CaPItaLs aNd SOMEtimes NoT you can build in
further security. When you make your password make sure that you
WILL NOT FORGET it. Since if you do messages are not legible and
the use of your secret key has gone. It might be wise to generate
some kind of a certificate containing this information (of course
be careful that nobody gets to your passphrase). See ``Revoke''.
After everything was entered the systems starts generating the keys.
This will take some time. During that time it needs to collect a lot
of random data. By working in a different screen you can help the
system collecting changing random data. As you understand by now, the
key will be always different. If you generate a key now and 5 minutes
later with exactly the same data, you'll get two different keys. Now
you must understand why you shouldn't forget your password.
33..22.. EExxppoorrttiinngg kkeeyyss
The command for exporting a key for a user is:
gpg --export [UID]
If no UID has been submitted all present keys will be exported. By
default the output is set to stdout. But with the -o option this is
sent to a file. It may be advisable using the option -a to write the
key to a 7-bit ASCII file instead of a binary file.
By exporting public keys you can broaden your horizon. Others can
start contacting you securely. This can be done by publishing it on
your homepage, by finger, through a key server like
http://www.pca.dfn.de/dfnpca/pgpkserv/ or any other method you can
think of.
33..33.. IImmppoorrttiinngg kkeeyyss
When you received someone's public key (or several public keys) you
have to add them to your key database in order to be able to use them.
To import into the database the command looks like this:
gpg --import [Filename]
if the filename is omitted the data will be read from stdin.
33..44.. RReevvookkee aa kkeeyy
For several reasons you may want to revoke an existing key. For
instance: the secret key has been stolen or became available to the
wrong people, the UID has been changed, the key is not large enough
anymore, etc. In all these cases the command to revoke the key is:
gpg --gen-revoke
This creates a revocation certificate. _T_o _b_e _a_b_l_e _t_o _d_o _t_h_i_s_, _y_o_u
_n_e_e_d _a _s_e_c_r_e_t _k_e_y, else anyone could revoke your certificate. This has
one disadvantage. If I do not know the passphrase the key has become
useless. But I cannot revoke the key! To overcome this problem it is
wise to create a revoke license when you create a key pair. And if you
do so, keep it safe! This can be on disk, paper, etc. Make sure that
this certificate will not fall into wrong hands!!!! If you don't
someone else can issue the revoke certificate for your key and make it
useless.
33..55.. KKeeyy aaddmmiinniissttrraattiioonn
With the GnuPG system comes a file that acts as some kind of database.
In this file all data regarding keys with the information that comes
with the keys is stored (everything until the Ownertrust values: for
more information on that read ``Key signing''). With
gpg --list-keys
all present keys will be displayed. To see the signatures as well
type:
gpg --list-sigs
(see ``Key signing'' for further information). To see the finger
prints type:
gpg --fingerprint
You want to see "Fingerprints" to ensure that somebody is really the
person they claim (like in a telephone call). This command will result
in a list of relatively small numbers.
To list the secret keys you type:
gpg --list-secret-keys
Note that listing fingerprints and signatures from private keys has no
use what soever.
In order to delete a public key you type:
gpg --delete-key UID
For deleting a secrete key you type:
gpg --delete-secret-key
There is one more important command that is relevant for working with
keys.
gpg --edit-key UID
Using this you can edit (among other things) the expiration date, add
a fingerprint and sing your key. Although it is too logic to mention.
For this you need your passphrase. When entering this you will see a
command line.
33..66.. KKeeyy ssiiggnniinngg
As mentioned before in the introduction there is one major Achilles'
heel in the system. This is the authenticity of public keys. If you
have a wrong public key you can say bye bye to the value of your
encryption. To overcome such risks there is a possibility of signing
keys. In that case you place your signature over the key, so that you
are absolutely positive that this key is valid. This leads to the
situation where the signature acknowledges that the user ID mentioned
in the key is actually the owner of that key. With that reassurance
you can start encrypting.
Using the gpg --edit-key UID command for the key that needs to be
signed you can sign it with the sign command.
_Y_o_u _s_h_o_u_l_d _o_n_l_y _s_i_g_n _a _k_e_y _a_s _b_e_i_n_g _a_u_t_h_e_n_t_i_c _w_h_e_n _y_o_u _a_r_e _A_B_S_O_L_U_T_E_L_Y
_S_U_R_E _t_h_a_t _t_h_e _k_e_y _i_s _r_e_a_l_l_y _a_u_t_h_e_n_t_i_c_!_!_!. So if you are positive you
got the key yourself (like on a key signing party) or you got the key
through other means and checked it (for instance by phone) using the
fingerprint-mechanism. You should never sign a key based on any
assumption.
Based on the available signatures and "ownertrusts" GnuPG determines
the validity of keys. Ownertrust is a value that the owner of a key
uses to determine the level of trust for a certain key. The values are
· 1 = Don't know
· 2 = I do NOT trust
· 3 = I trust marginally
· 4 = I trust fully
If the user does not trust a signature it can say so and thus
disregard the signature. Trust information is not stored in the
same file as the keys, but in a separate file.
44.. EEnnccrryypptt aanndd ddeeccrryypptt
After installing everything and configuring everything in the way we
want, we can start on encrypting and decrypting.
When encrypting or decrypting it is possible to have more than one
private key in use. If this occurs you need to select the active key.
This can be done by using the option -u UID or by using the option
--local-user UID. This causes the default key to use to be replaced
by wanted key.
If you want to change recipient this can be done by the option -r or
by the option --recipient.
44..11.. EEnnccrryypptt
The command to encrypt is
gpg -e Recipient [Data]
or
gpg --encrypt Recipient [Data]
To avoid the risk that somebody else claims to be you, it is very use
ful to sign everything you encrypt, see ``signatures''.
44..22.. DDeeccrryypptt
The command for decrypting is:
gpg [-d] [Data]
or
gpg [--decrypt] [Data]
Also here stdout is preset, but with the -o option you can redirect
the output to a file.
55.. SSiiggnniinngg aanndd cchheecckkiinngg ssiiggnnaattuurreess
To sign data with your own key, use the command:
gpg -s (or --sign) [Data]
By doing this also compression takes place. This means that the result
is not legible. If you want a legible result you can use:
gpg --clearsign [Data]
this will make sure that the results are clearly legible. Furthermore
it does the same (signing data).
With
gpg -b (or --detach-sign) [Data]
you can write the signature in a separate file. It is highly recom
mended to use this option especially when signing binary files (like
archives for instance). Also the --armor option can be extremely use
ful here.
Quite often you find that data is encrypted and signed as well. The
full instruction looks like:
gpg [-u Sender] [-r Recipient] [--armor] --sign --encrypt [Data]
The functionality of the options -u (--local-user) and -r
(--recipient) are as described before.
When encrypted data has been signed as well, the signature is checked
when the data is decrypted. You can check the signature of signed data
by using the command:
gpg [--verify] [Data]
This will only work (of course) when you own the public key of the
sender.
66.. FFrroonntt eennddss
To make life a lot easier in using GnuPG, you have a wide choice of
programs that either use or support GnuPG encryption. There are
graphical front ends that put your key administration at the click of
a mouse button and many MUAs (Mail User Agents) let you encrypt and
sign your Email messages seamlessly. A nearly full list of front ends
is available from the GnuPG Frontends page. We will highlight a few
of them in this section.
66..11.. GGrraapphhiiccaall iinntteerrffaacceess
66..11..11.. GGPPAA
GPA, the _G_N_U _P_r_i_v_a_c_y _A_s_s_i_s_t_a_n_t is a graphical user interface for the
GNU Privacy Guard (GnuPG). This is the standard graphical front end,
provided by the GnuPG project. With GPA, you can view your keyring,
import and export keys, generate keys, edit key properties and
encrypt, sign or decrypt documents. Installing GPA is easy. Download
the tarball, unpack and do the usual
./configure; make; make install.
Start the program by typing
gpa
66..11..22.. SSeeaahhoorrssee
Seahorse is a GNOME front-end for GnuPG. It can be used for sign,
encrypt, verify and decrypt text and files. The text can be taken
from the clipboard, or written directly in the little editor it has.
Seahorse is also a key manager, which can be used to edit almost all
the properties of the keys stored in your key rings. You can install
Seahorse from a Debian package (RPMs are not available at this time)
or from the source tarball. Installing from source is like any other
package. Download, untar, configure and make install. The
installation puts seahorse in /usr/local and puts a menu item in the
Gnome 'Applications' menu.
66..11..33.. GGeehheeiimmnniiss
KGPG is a front end for GnuPG which is based upon KDE. KGPG supports
key signing, importing and exporting. It can also work with other KDE
tools interactively like konquerer.
66..22.. EEmmaaiill pprrooggrraammss
Most popular Email programs (or MUAs) support GnuPG. Among these are
at least the following:
· Mozilla
· Evolution
· Pine
· Kmail
· Eudora
· Mutt
· exmh
There are probably more; it is hardly possible to try them all.
Using GnuPG support in your mail program lets you decrypt Email
messages sent to you that are encrypted with your public key, sign
your messages so the receiving party can make sure you are the author
and encrypt your Email with the public keys of your recipients.
66..22..11.. MMoozziillllaa aanndd EEnniiggmmaaiill
Mozilla does not have GnuPG support in itself. To use GnuPG encryption
with Mozilla, you must install a plug-in, such as EnigMail. Enigmail
is a "plugin" for Mozilla/Netscape Mail which allows users to access
the authentication and encryption features provided by the popular GPG
and PGP software. Enigmail can encrypt/sign mail when sending, and
also decrypt/authenticate received mail. It can also import/export
public keys.
Enigmail can easily be installed by Mozilla extension management. The
only thing you should do is to click on the proper link related with
your Mozilla version on the Download page. Unfortunately, RPMs for
enigmail are not available.
66..22..22.. EEvvoolluuttiioonn
Evolution is a well-known MUA for Linux and has fairly good GnuPG
support. It can get e-mails encrypted and decrypt them. It also has
built in key signing and key authorising options. It supports S/MIME
but inline pgp support (which is not standard but used by some MUAs)
is not implemented. To configure the GnuPG settings you should check
the mail account preferences.
66..22..33.. KKmmaaiill
Kmail, the standard Email program for KDE has integrated support for
GnuPG and PGP encryption. To set things up so you can sign and
decrypt messages, you have to enter your GnuPG user ID in the
'Identity' section of the Kmail configuration. When you send a new
message, the message will not be signed or encrypted by default. You
have to check the 'Sign message' and 'Encrypt message' buttons in the
tool bar.
77.. SSoouurrcceess ooff iinnffoorrmmaattiioonn
77..11.. GGnnuuPPGG
· The GnuPG Homepage <http://www.gnupg.org>
· The GnuPG Mailing list, including archives and descriptions on the
GnuPG Homepage.
· The information enclosed in the GnuPG project (updated until
version 0.9.2), however not yet very extensively done. And not to
forget:
gpg --help
. This is very valuable information.
77..22.. PPGGPP
PGP is the older and (still) widely spread and used cryptography
program. Through the years a lot of documents have been made. This
can be considered as very useful information. A lot of that
information is so general that you can apply that to GnuPG as well.
Check out the following URLs for these documents:
· The International PGP Homepage <http://www.pgpi.com>
· The PGP DH vs. RSA FAQ <http://www.scramdisk.clara.net/pgpfaq.html>
has information on the differences of these two algorithms. These
are the two algorithms used by GnuPG.
77..33.. KKeeyysseerrvveerrss
· Keyserver.net <http://www.keyserver.net>
· <http://wwwkeys.eu.pgp.net>
77..44.. BBooookkss
· B. Schneier, "Applied Cryptography, Second Edition", Wiley, 1996
Deutsche Ausgabe unter dem Titel "Angewandte Kryptographie",
Addison-Wesley, 1996
88.. AAbboouutt tthhiiss ddooccuummeenntt
Copyright © 1999 Brenno J.S.A.A.F. de Winter (English version)
Copyright © 1999 Michael Fischer v. Mollard (original German version)
Copyright © 2002 Arjen Baart (Dutch version) Copyright © 2004 Baris
Cicek (Turkish version)
This document is free documentation you can redistribute it and/or
modify it under the terms of the GNU Library General Public License as
published by the Free Software Foundation; either version 2 of the
License, or (at your option) any later version.
This library is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
USA.
88..11.. VVeerrssiioonnss
Original German versions: Version 0.1 was the first version in German
VVeerrssiioonn 00..11..00 ((EEnngglliisshh)) AApprriill 3300tthh 11999999,, DDuuttcchh QQuueeeenn''ss DDaayy..
· This version is the translation of the German version in English
with some adjustments.
VVeerrssiioonn 00..11..11 ((GGeerrmmaann))
· New section "Boundaries to security"
· Improved explanation of signatures
· Changes after comments from Werner Koch (thanks!)
VVeerrssiioonn 00..11..22 ((EEnngglliisshh)) AApprriill 33,, 22000022
· Corrected a few typos.
· New section about front ends.
VVeerrssiioonn 00..11..33 ((DDuuttcchh)) MMaayy 1177,, 22000022
· This version is a translation of the English version into Dutch.
VVeerrssiioonn 00..11..44 ((TTuurrkkiisshh)) MMaayy 33,, 22000044
· This version is a translation of the English version into Turkish.
Also some additions are made on English version. Broken links are
fixed. Frontends are revised.
All changes are documented in a diff file: dieses Dokument
<http://www.stud.uni-goettingen.de/~s070674/GnuPGMiniHowto/>
For the English or Dutch version: All remarks for this document can be
sent to Brenno J.S.A.A.F. de Winter (brenno@dewinter.com). or Arjen
Baart (arjen@andromeda.nl). Comments help us make a better document
and are greatly appreciated.
For the German version: Anregungen, Kritik, Verbesserungen und
Erweiterungen einfach an Michael Fischer v. Mollard (fischer@math.uni-
goettingen.de) senden, damit dieses Dokument weiter verbessert werden
kann.
For the Turkish version: Baris Cicek (baris teamforce.name.tr)
# Encrypt using your own public key.
# This will encrypt the file into <name>.gpg
# Use --output to specify output name.
# Dont use --armor if you dont want ascii armored file.
gpg --armor -r KeyID@provider.gr -e DS.TXT
# decrypt your encrypted file into a test file for checks.
gpg --output testthis.txt -d DS.TXT.asc
# Test both files with common hash functions to check their validity:
sha1sum DS.TXT
sha1sum DS.TXT.asc
sha256sum DS.TXT
sha256sum DS.TXT.asc
md5sum DS.TXT
md5sum DS.TXT.asc
# There are two ways to set the priority of used algorithms
# for ciphers and digests, one is from inside the key editing
# screens, the other is from editting the gnu.conf file.
# Key Editing
gpg --edit-key [key-id]
# Show used algorithms
>showpref
# Changing the defaults. Caution: setpref cannot change only some preferred
# algorithms (like only digest algorithms), we have to list all three categories
# at the same time.
>setpref SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
# Save and quit
>save
>quit
# CLI
# Expert tip: If you really want to force the algorithm used, you can use the
# --cipher-algo name command-line switch for symmetric or public-key encryption.
# The --personal-cipher-preferences options above should be used if you don't
# want to accidentally violate the OpenPGP specification. You can use the --cipher-algo
# name argument if you know that your recipient has a modern version of GPG but
# doesn't have their public key set up well. Again, encourage them to improve
# their public key using the Using Stronger Algorithms section above.
# without compression pref
gpg --armor --personal-cipher-preferences "AES256 AES192 AES" --personal-digest-preferences "SHA512 SHA256 SHA1" -r recipient1@email.address --encrypt filename
# with compression pref.
gpg --armor --personal-compress-preferences "zlib zip" string--personal-cipher-preferences "AES256 AES192 AES" --personal-digest-preferences "SHA512 SHA256 SHA1" -r recipient1@email.address --encrypt filename
# gpg.conf file
# The third way is to enable/add lines to the gpg.conf file. That file is located
# in /.gnupg and is the main file that holds all the configurations. You can add
# these lines in that file to affect the cipher/digest/zip preferences.
personal-digest-preferences SHA256
cert-digest-algo SHA256
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
########################################################################
# SAMPLE gnu.conf file
# These first three lines are not copied to the gpg.conf file in
# the users home directory.
# $Id$
# Options for GnuPG
# Copyright 1998, 1999, 2000, 2001, 2002, 2003,
# 2010 Free Software Foundation, Inc.
#
# This file is free software; as a special exception the author gives
# unlimited permission to copy and/or distribute it, with or without
# modifications, as long as this notice is preserved.
#
# This file is distributed in the hope that it will be useful, but
# WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
# implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
#
# Unless you specify which option file to use (with the command line
# option "--options filename"), GnuPG uses the file ~/.gnupg/gpg.conf
# by default.
#
# An options file can contain any long options which are available in
# GnuPG. If the first non white space character of a line is a '#',
# this line is ignored. Empty lines are also ignored.
#
# See the man page for a list of options.
# Uncomment the following option to get rid of the copyright notice
#no-greeting
# If you have more than 1 secret key in your keyring, you may want to
# uncomment the following option and set your preferred keyid.
#default-key 621CC013
# If you do not pass a recipient to gpg, it will ask for one. Using
# this option you can encrypt to a default key. Key validation will
# not be done in this case. The second form uses the default key as
# default recipient.
#default-recipient some-user-id
#default-recipient-self
# By default GnuPG creates version 4 signatures for data files as
# specified by OpenPGP. Some earlier (PGP 6, PGP 7) versions of PGP
# require the older version 3 signatures. Setting this option forces
# GnuPG to create version 3 signatures.
#force-v3-sigs
# Because some mailers change lines starting with "From " to ">From "
# it is good to handle such lines in a special way when creating
# cleartext signatures; all other PGP versions do it this way too.
# To enable full OpenPGP compliance you may want to use this option.
#no-escape-from-lines
# When verifying a signature made from a subkey, ensure that the cross
# certification "back signature" on the subkey is present and valid.
# This protects against a subtle attack against subkeys that can sign.
# Defaults to --no-require-cross-certification. However for new
# installations it should be enabled.
require-cross-certification
# If you do not use the Latin-1 (ISO-8859-1) charset, you should tell
# GnuPG which is the native character set. Please check the man page
# for supported character sets. This character set is only used for
# metadata and not for the actual message which does not undergo any
# translation. Note that future version of GnuPG will change to UTF-8
# as default character set.
#charset utf-8
# Group names may be defined like this:
# group mynames = paige 0x12345678 joe patti
#
# Any time "mynames" is a recipient (-r or --recipient), it will be
# expanded to the names "paige", "joe", and "patti", and the key ID
# "0x12345678". Note there is only one level of expansion - you
# cannot make an group that points to another group. Note also that
# if there are spaces in the recipient name, this will appear as two
# recipients. In these cases it is better to use the key ID.
#group mynames = paige 0x12345678 joe patti
# Some old Windows platforms require 8.3 filenames. If your system
# can handle long filenames, uncomment this.
#no-mangle-dos-filenames
# Lock the file only once for the lifetime of a process. If you do
# not define this, the lock will be obtained and released every time
# it is needed - normally this is not needed.
#lock-once
# GnuPG can send and receive keys to and from a keyserver. These
# servers can be HKP, email, or LDAP (if GnuPG is built with LDAP
# support).
#
# Example HKP keyservers:
# hkp://keys.gnupg.net
# hkp://subkeys.pgp.net
#
# Example email keyserver:
# mailto:pgp-public-keys@keys.pgp.net
#
# Example LDAP keyservers:
# ldap://pgp.surfnet.nl:11370
# ldap://keyserver.pgp.com
#
# Regular URL syntax applies, and you can set an alternate port
# through the usual method:
# hkp://keyserver.example.net:22742
#
# If you have problems connecting to a HKP server through a buggy http
# proxy, you can use keyserver option broken-http-proxy (see below),
# but first you should make sure that you have read the man page
# regarding proxies (keyserver option honor-http-proxy)
#
# Most users just set the name and type of their preferred keyserver.
# Note that most servers (with the notable exception of
# ldap://keyserver.pgp.com) synchronize changes with each other. Note
# also that a single server name may actually point to multiple
# servers via DNS round-robin. hkp://keys.gnupg.net is an example of
# such a "server", which spreads the load over a number of physical
# servers. To see the IP address of the server actually used, you may use
# the "--keyserver-options debug".
keyserver hkp://keys.gnupg.net
#keyserver http://http-keys.gnupg.net
#keyserver mailto:pgp-public-keys@keys.nl.pgp.net
#keyserver ldap://pgp.surfnet.nl:11370
#keyserver ldap://keyserver.pgp.com
# Common options for keyserver functions:
#
# include-disabled = when searching, include keys marked as "disabled"
# on the keyserver (not all keyservers support this).
#
# no-include-revoked = when searching, do not include keys marked as
# "revoked" on the keyserver.
#
# verbose = show more information as the keys are fetched.
# Can be used more than once to increase the amount
# of information shown.
#
# use-temp-files = use temporary files instead of a pipe to talk to the
# keyserver. Some platforms (Win32 for one) always
# have this on.
#
# keep-temp-files = do not delete temporary files after using them
# (really only useful for debugging)
#
# honor-http-proxy = if the keyserver uses HTTP, honor the http_proxy
# environment variable
#
# broken-http-proxy = try to work around a buggy HTTP proxy
#
# auto-key-retrieve = automatically fetch keys as needed from the keyserver
# when verifying signatures or when importing keys that
# have been revoked by a revocation key that is not
# present on the keyring.
#
# no-include-attributes = do not include attribute IDs (aka "photo IDs")
# when sending keys to the keyserver.
#keyserver-options auto-key-retrieve
# Uncomment this line to display photo user IDs in key listings and
# when a signature from a key with a photo is verified.
#show-photos
# Use this program to display photo user IDs
#
# %i is expanded to a temporary file that contains the photo.
# %I is the same as %i, but the file isn't deleted afterwards by GnuPG.
# %k is expanded to the key ID of the key.
# %K is expanded to the long OpenPGP key ID of the key.
# %t is expanded to the extension of the image (e.g. "jpg").
# %T is expanded to the MIME type of the image (e.g. "image/jpeg").
# %f is expanded to the fingerprint of the key.
# %% is %, of course.
#
# If %i or %I are not present, then the photo is supplied to the
# viewer on standard input. If your platform supports it, standard
# input is the best way to do this as it avoids the time and effort in
# generating and then cleaning up a secure temp file.
#
# The default program is "xloadimage -fork -quiet -title 'KeyID 0x%k' stdin"
# On Mac OS X and Windows, the default is to use your regular JPEG image
# viewer.
#
# Some other viewers:
# photo-viewer "qiv %i"
# photo-viewer "ee %i"
# photo-viewer "display -title 'KeyID 0x%k'"
#
# This one saves a copy of the photo ID in your home directory:
# photo-viewer "cat > ~/photoid-for-key-%k.%t"
#
# Use your MIME handler to view photos:
# photo-viewer "metamail -q -d -b -c %T -s 'KeyID 0x%k' -f GnuPG"
personal-digest-preferences SHA256
cert-digest-algo SHA256
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
# My way - gpg(1)
echo "testpass" | gpg --passphrase-fd 0 --personal-cipher-preferences "AES256 AES192 AES" --personal-digest-preferences "SHA256" --encrypt --sign --armor --output "D9670.pgp" -r "DIASSARSAPROD" "D9670"
# --batch yes - gpg(2) - Requires --batch option
echo your_password | gpg --batch --yes --passphrase-fd 0 your_file.gpg
echo "YOUR_PASS_PHRASE" | gpg --batch --yes --passphrase-fd 0 /home/somewhere/your_file.pgp
# Using a password file - gpg(2)
gpg --pinentry-mode loopback --passphrase-file=file encrypted.gpg
# Using --no-use-agent - gpg(1.4.16)
gpg --cipher-algo aes256 --output foo.gpg --passphrase-file ./passphrase --batch --yes --no-use-agent --symmetric foo
# Using --no-tty
read -sp "Enter passphrase: " pass
echo "${pass}" | gpg --batch --no-tty --yes --passphrase-fd 0 --symmetric -o /path/to/saved/file.jpg.gpg /path/to/file.jpg
echo "${pass}" | gpg --batch --no-tty --yes --passphrase-fd 0 --decrypt -o /path/to/decrypted/file.jpg /path/to/encrypted/file.jpg.gpg
# Using gnu.conf edit
Put at the end of ~/.gnupg/gpg.conf:
use-agent
pinentry-mode loopback
Put at the end of (maybe new) file ~/.gnupg/gpg-agent.conf:
allow-loopback-pinentry
And then run this command:
echo RELOADAGENT | gpg-connect-agent
Now you are able to run this without asking password:
echo "$1" | gpg2 --trust-model always --clearsign --batch --no-tty --quiet --no-verbose --yes -u $2 --digest-algo SHA512
--s2k-digest-algo SHA512 --passphrase "$3"
Where $1 is the text to be encrypted, $2 is the user ID and $3 the password.
Note: I cant remember why it works, but it works. If you know the details, please
edit and insert here
# for gpg 2
gpg2 -se --passphrase yourpassword --batch --yes -r user@example.com filename
# gnupg(2) relevant man page:
--passphrase-fd n
Read the passphrase from file descriptor n. Only the first line will be read
from file descriptor n. If you use 0 for n, the passphrase will be read from STDIN.
This can only be used if only one passphrase is supplied.
--passphrase-file file
Read the passphrase from file file. Only the first line will be read from file
file. This can only be used if only one passphrase is supplied. Obviously, a
passphrase stored in a file is of questionable security if other users can read
this file. Dont use this option if you can avoid it.
--passphrase string
Use string as the passphrase. This can only be used if only one passphrase is
supplied. Obviously, this is of very questionable security on a multi-user system.
Dont use this option if you can avoid it.
add --pinentry-mode loopback in order to work
Note that since Version 2.0 this passphrase is only used if the option --batch
has also been given. Since Version 2.1 the --pinentry-mode also needs to be set
to loopback.
For example:
gpg --batch --yes --passphrase="pw" --pinentry-mode loopback -o out -d in# gpg does not add the zlip/bzip/zip suffix, it simply compresses the file.
# gpg compresses by default. A diff algorithm can be set using --compress-algo name
# the default is zip lvl 6
--compress-algo n Use compress algorithm n.
Default is 2 which is RFC1950 compression. You may use 1 to use the old zlib version (RFC1951) which is used by PGP. The default algorithm may give better results because the window size is not limited to 8K. If this is not used the OpenPGP behavior is used, i.e. the compression algorithm is selected from the preferences; note, that this cant be done if you do not encrypt the data.
# Set specific compression algorithm during compression
echo "testpass" | gpg --passphrase-fd 0 --personal-cipher-preferences "AES256 AES192 AES" --personal-digest-preferences "SHA256" --encrypt --sign --armor --compress-algo "zip" --output "zipD9670.gpg" -r "DIASSARSAPROD" "D9670"
# Using personal-compress
# Compression: Uncompressed, ZIP, ZLIB, BZIP2
--personal-compress-preferences string
gpg --armor --personal-compress-preferences "zlib zip" string--personal-cipher-preferences "AES256 AES192 AES" --personal-digest-preferences "SHA512 SHA256 SHA1" -r recipient1@email.address --encrypt filename
# View available compression algorithms
gpg --version
# Disable compression entirely
-z 0
-compress level 0
/usr/bin/gpg --trust-model always --encrypt --compress-algo none --recipient 'YOUR KEY NAME HERE' file.tar
#To run the command in background use:
nohup /usr/bin/gpg --trust-model always --encrypt --compress-algo none --recipient 'YOUR KEY NAME HERE' file.tar > /dev/null 2>&1 &
13.3 Commonly Seen Problems
Error code ‘Not supported’ from Dirmngr
Most likely the option enable-ocsp is active for gpgsm but Dirmngr’s OCSP feature has not been enabled using allow-ocsp in dirmngr.conf.
The Curses based Pinentry does not work
The far most common reason for this is that the environment variable GPG_TTY has not been set correctly. Make sure that it has been set to a real tty device and not just to ‘/dev/tty’; i.e. ‘GPG_TTY=tty’ is plainly wrong; what you want is ‘GPG_TTY=`tty`’ — note the back ticks. Also make sure that this environment variable gets exported, that is you should follow up the setting with an ‘export GPG_TTY’ (assuming a Bourne style shell). Even for GUI based Pinentries; you should have set GPG_TTY. See the section on installing the gpg-agent on how to do it.
SSH hangs while a popping up pinentry was expected
SSH has no way to tell the gpg-agent what terminal or X display it is running on. So when remotely logging into a box where a gpg-agent with SSH support is running, the pinentry will get popped up on whatever display the gpg-agent has been started. To solve this problem you may issue the command
echo UPDATESTARTUPTTY | gpg-connect-agent
and the next pinentry will pop up on your display or screen. However, you need to kill the running pinentry first because only one pinentry may be running at once. If you plan to use ssh on a new display you should issue the above command before invoking ssh or any other service making use of ssh.
Exporting a secret key without a certificate
It may happen that you have created a certificate request using gpgsm but not yet received and imported the certificate from the CA. However, you want to export the secret key to another machine right now to import the certificate over there then. You can do this with a little trick but it requires that you know the approximate time you created the signing request. By running the command
ls -ltr ~/.gnupg/private-keys-v1.d
you get a listing of all private keys under control of gpg-agent. Pick the key which best matches the creation time and run the command
/usr/local/libexec/gpg-protect-tool --p12-export \
~/.gnupg/private-keys-v1.d/foo >foo.p12
(Please adjust the path to gpg-protect-tool to the appropriate location). foo is the name of the key file you picked (it should have the suffix .key). A Pinentry box will pop up and ask you for the current passphrase of the key and a new passphrase to protect it in the pkcs#12 file.
To import the created file on the machine you use this command:
/usr/local/libexec/gpg-protect-tool --p12-import --store foo.p12
You will be asked for the pkcs#12 passphrase and a new passphrase to protect the imported private key at its new location.
Note that there is no easy way to match existing certificates with stored private keys because some private keys are used for Secure Shell or other purposes and don’t have a corresponding certificate.
A root certificate does not verify
A common problem is that the root certificate misses the required basicConstraints attribute and thus gpgsm rejects this certificate. An error message indicating “no value” is a sign for such a certificate. You may use the relax flag in trustlist.txt to accept the certificate anyway. Note that the fingerprint and this flag may only be added manually to trustlist.txt.
Error message: “digest algorithm N has not been enabled”
The signature is broken. You may try the option --extra-digest-algo SHA256 to workaround the problem. The number N is the internal algorithm identifier; for example 8 refers to SHA-256.
The Windows version does not work under Wine
When running the W32 version of gpg under Wine you may get an error messages like:
gpg: fatal: WriteConsole failed: Access denied
The solution is to use the command wineconsole.
Some operations like --generate-key really want to talk to the console directly for increased security (for example to prevent the passphrase from appearing on the screen). So, you should use wineconsole instead of wine, which will launch a windows console that implements those additional features.
Why does GPG’s –search-key list weird keys?
For performance reasons the keyservers do not check the keys the same way gpg does. It may happen that the listing of keys available on the keyservers shows keys with wrong user IDs or with user Ids from other keys. If you try to import this key, the bad keys or bad user ids won’t get imported, though. This is a bit unfortunate but we can’t do anything about it without actually downloading the keys.Migration Checklist
This list is based on the excellent instructions from Debian.
Set defaults in ~/.gnupg/gpg.conf and ~/.caff/gnupghome/gpg.conf:
personal-digest-preferences SHA512
cert-digest-algo SHA512
default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
Generate a RSA/RSA key with 4096 bits. (gpg --gen-key)
Edit the newly created key (gpg --edit-key NEWID):
Validate that the preferences list the stronger ciphers first (showpref):
Cipher: AES256, AES192, AES, CAST5, 3DES
Digest: SHA512, SHA384, SHA256, SHA224, SHA1
Compression: ZLIB, BZIP2, ZIP, Uncompressed
Features: MDC, Keyserver no-modify
Add all the needed email addresses (adduid)
Set primary uid (uid and primary)
Save changes (save)
Generate revocation cert and save somewhere safe (gpg --gen-revoke NEWID > NEWID-revoke.asc)
Sign the new key with the old key (gpg --sign-key NEWID)
Publish new key (gpg --keyserver pgp.mit.edu --send-key NEWID, gpg --keyserver keyserver.ubuntu.com --send-key NEWID)
Write up transition statement (see here for examples)
Sign transition statement with both keys (gpg -u OLDID -u NEWID --clearsign transition.txt)
Publish transition (blog, twitter, etc)
Collect signatures
Add to Launchpad: [https://launchpad.net/people/+me/+editpgpkeys]
Sign things that are still active with your new key and send to their owners.
You can validate signatures are using non-SHA1 by using gpg --list-packets < SIGFILE, and checking that digest algo (aka hash algorithm) is not "2" (SHA1). For SHA512, you'd want "10" (see RFC4880 section 9.4 for details):
:signature packet: algo 1, keyid xxxxxxxxxxxxxxxx
version 4, created 1285621931, md5len 0, sigclass 0x10
digest algo 10, begin of digest e3 3f
You can validate the cipher (symmetric key) algorithm of an encrypted message is AES256 by using gpg -o /dev/null --show-session-key < ENCFILE, and checking that the algorithm is "9" (AES256, see RFC4880 section 9.2 for details). The cipher is listed as an integer before the colon. Eg:
gpg: session key: `9:5E73B30F5A8F35D8282C9F3B9EE5C4943E06D59A0E65D9AFADD5998525F792CA'
You can validate the public key algorithm of an encrypted message is RSA by using gpg --list-packets < ENCFILE, and checking that the algorithm is "1" (RSA (Encrypt or Sign) [HAC], see RFC4880 section 9.1 for details). Eg:
:pubkey enc packet: version 3, algo 1, keyid 8CB1FAB0888C8DEC
data: [4096 bits]
For messages both encrypted and signed, you should be able to use gpg -d -o /dev/null -v < ENCFILE to verify the public key algorithm, the digest/hash algorithm and the cipher/symmetric-key algorithm. Eg:
gpg: encrypted with 4096-bit RSA key...
gpg: AES256 encrypted data
gpg: using PGP trust model
gpg: binary signature, digest algorithm SHA512
If that doesn't work:
validate the public key algorithm as above
decrypt the message
validate the digest algorithm of the decrypted message (which should contain the signature) as above.
Make new key your default ( ~/.gnupg/gpg.conf, ~/.caffrc, ~/.devscripts, ~/.muttrc, your MUA, etc)
NOTE: Be careful if your new key uses the same email address, name and comment as your old key, because GnuPG will use the first key it finds in your secret keyring for signing and encrypting when not specifying a numerical ID (eg, debsign), and therefore your old key will continue to be used. You know that you will have this problem if the gpg --list-keys YOUREMAILADDRESS lists your old key first. This can be fixed in one of a few ways:
For each application that uses gnupg, specify the numerical KEYID of your new key (eg, 'AAAABBBB') instead of the email address. This is the safest method, but takes more work. Eg, for devscripts, create/modify ~/.devscripts to have something like:
DEBSIGN_KEYID="AAAABBBB"
You can also change the order of your keyring. Eg:
make a backup of ~/.gnupg with cp -a ~/.gnupg ~/.gnupg.bak
create a safe directory with mkdir -m0700 ~/gpg && cd ~/gpg
export your public key with gpg --export OLDID > ~/gpg/oldpub.gpg
export your secret key with gpg --export-secret-keys OLDID > ~/gpg/oldsec.gpg
delete your old public and secret key with gpg --delete-secret-and-public-key OLDID
import your old public key with gpg --import ~/gpg/oldpub.gpg
import your old secret key with gpg --import ~/gpg/oldsec.gpg
verify it worked with gpg --list-keys YOUREMAILADDRESS. Your new key should now be listed first. Compare it to your backup with gpg --no-default-keyring --keyring ~/.gnupg.bak/pubring.gpg --secret-keyring ~/.gnupg.bak/secring.gpg --list-keys YOUREMAILADDRESS
if all went well, clean up the exported keys with rm -f ~/gpg/oldpub.gpg ~/gpg/oldsec.gpg && rmdir ~/gpg
sign, trust and enable the old key with gpg --edit-key OLDID
Lastly, you can export your old public and secret key into another keyring, then delete the old keys from your default keyring (again, make backups!). This way for normal every day work your new key can be used. The main problem with this is that your mailer won't be able to decrypt email encrypted with your old key. You can access your old key with gpg by using the --keyring and --secret-keyring options, which adds these keyring to the list of available keyrings. Eg gpg --keyring pubring_OLDID.gpg --secret-keyring secring_OLDID.gpg --list-keys.
When ready (e.g. 90 days), publish revocation cert for the old key.