rlh   img   mp3   nfo   pro  
<!-- X-URL: https://codesorcery.net/old/mutt/mutt-gnupg-howto -->
<!-- Date: Thu, 08 Oct 2020 21:16:05 GMT -->
<!-- Last-Modified: Thu, 20 Dec 2012 07:42:23 GMT -->
<BASE HREF="https://codesorcery.net/old/mutt/mutt-gnupg-howto">


      Everything You Need To Know To Start Using GnuPG with Mutt


             By Justin R. Miller <justin@solidlinux.com>

              Revision 0.1, Released 23 September 2001


     I. Purpose
    II. Overview
   III. Assumptions
    IV. Configuring GnuPG
     V. Protecting Your Private Key
    VI. Publicizing Your Public Key
   VII. Understanding Validity and Your Web of Trust
  VIII. Understanding The Need For Message Signatures
    IX. Understanding How Signatures Are Made
     X. Understanding How Encryption Is Done
    XI. A Practical Example of Manual Key Management
   XII. A Practical Example of Manual Signing and Verification
  XIII. A Practical Example of Manual Encryption and Decryption
   XIV. Configuring Mutt For Use With GnuPG
    XV. Trying It All Out
   XVI. Links For More Information
  XVII. Contributors
 XVIII. Feedback


I. Purpose

I'm writing this document for a couple of reasons.  Firstly, I believe
that everyone should be using encryption and signatures in their email.  

Secondly, I believe that if you are already using a mail client such as
Mutt (which a lot of people are), then there is absolutely no reason for
you not to be using PGP-compatible software.  

Thirdly, all of the documentation that I've seen thus far is geared
toward someone who is already familiar with PGP, so it just explains
things like how to configure Mutt to do such tasks as automatically sign
outgoing messages or write a procmail recipe to rewrite old-style inline
PGP messages as S/MIME messages.  This info means little if you don't
understand the technical jargon.  By no means do I want to trample the
existing documentation for Mutt or GnuPG, the Mutt-i, GnuPG and PGP
Howto, nor any other existing documentation.  I want simply to provide a
resource for the use of Mutt with GnuPG exclusively and to summarize the
important points of the whole matter so that one can get started quickly
and responsibly.  

Fourthly, I am trying to promote both Mutt and GnuPG, as free software
projects, for use in everyday communications.  

Lastly, I enjoy writing tutorials and I hope that this one is of use to
many people.  I did a lot of research and I figured a number of things
out on my own, and now I want to help people along.  


II. Overview

When you are finished with this document, you will be able to send and
receive cryptographically signed and/or encrypted email with the Mutt
mail reader and GnuPG, the GNU software implementation of OpenPGP
(RFC2440).  If you want to know why you should use encryption, please
read about that topic first (see the links at the end of this document).  

Using GnuPG with Mutt is quite easy, but the main things to be learned
are the details and the theory behind the actual actions.  This document
will explain the need for signing and how to sign messages, how to
verify signatures on mail sent to you, how to encrypt messages, and how
to decrypt messages.  It will also show you, within the scope of Mutt,
how to collect and manage the public keys of your correspondents and how
to manage your own private key.  Lastly, it will show you how to
publicize your own public key and how to encourage others to use PGP
when communicating with you.  


III. Assumptions

Before reading this document, you should have a working knowledge of the
Mutt mail reader and you should know the basics of public key
cryptography.  You should understand that a public key is for others to
use when encrypting messages to you and when verifying signatures from
you, and that a private key is used for creating signatures and for
decrypting messages to you.  


IV. Configuring GnuPG

Follow the instructions that came with GnuPG in order to create a
private and public key.  If you are not sure what values to use, pick
the default values for key type and key size and use your name and email
address as you would normally address your email.  

The only other thing that you might want to do is to configure GnuPG to
automatically fetch public keys as necessary.  This comes in very handy
with Mutt, as you won't have to go and download and import a key
manually in another terminal.  In order to do this, add this line to
your ~/.gnupg/options file:  

    keyserver <keyserver address>

Some good keyservers are:  


Please note that key retrievals do not happen over HTTP and as such, the
keyserver address should not start with 'http://'.  

You may test this out by retrieving my public key:

    gpg --recv-keys 0xC9C40C31

You may then confirm that the key was added to your keyring:  

    gpg --list-keys justin


V. Protecting Your Private Key

The most important security points to remember in all of this are to
protect your private keyring file, and above that, to protect your
passphrase.  There is still a chance that your private key can be
cracked without the passphrase, but it is slim in the hands of one

You should limit the number of machines on which your private key is
copied.  You should only transfer your private key via a floppy disk or
other physical media.  If you do not trust the environment on which you
will be working to be free from the possiblity of snooping (i.e. a work
computer where others have access to your personal files), then you
should not introduce your private key to this environment.  Either that,
or you should create a separate key for use as a "work key" and keep
your "home key" in a safe environment.  

Theft of your private key by anyone means theft of your identity.  In an
increasingly digital world, your private key will soon carry as much
weight as a photo ID, and in some situations already carries more.  


VI. Publicizing Your Public Key

People will need your public key both to verify signed messages by you
and to send you encrypted messages.  You can make it available by
putting it on a website, publishing it in print, mailing it via email or
postal mail, faxing it, uploading it to a keyserver, or any number of
other means.  

The more places your public key is put, the better, since there is a
lower chance of all of them being modified and distributed falsely.
However, just because a key can be obtained from multiple places and all
copies may match doesn't mean that the key should be considered valid.
A key should only be considered valid (i.e. truly belonging to its
owner) if it does so within your web of trust (see next section).  To
clarify, you can determine whether or not a message originated from a
particular key, but you cannot, aside from a validity check, determine
whether that key belongs to who it seems to belong to.  

You can find my public key in this document, by searching a keyserver
for key ID 0xC9C40C31 or my name, or from my website.  In addition, Mutt
makes it easy to send your public key to someone (once Mutt is
configured to work with GnuPG as described below) through the Esc-k key

You may also add an X-header to your outgoing mail to provide key
download information.  All of my personal mail includes this header:  

    X-PGP-Key: http://solidlinux.com/~justin/pubkey.asc

All of these approaches, as well as signing all outgoing mail, help
publicize the fact that you wish to use cryptography for secure email
communication.  These things will also often generate questions about
what the signature attachment means or why you have a file full of
garbled characters on your website.  This lets you have all the more
chances to publicize PGP usage and awareness.  

There is considerable debate as whether signing messages that are sent
out to mass audiences (via mailing lists and the like) is appropriate.
I hope to make available in the near future some arguments for both
sides of this debate, but if you'd like more info, you can search the
mutt-users and gnupg-users mailing list archives. 


VII. Understanding Validity and Your Web of Trust

'Validity' for a particular key refers to the knowledge that the key
belongs to the person to whom you expect it to belong.  This knowledge
comes about based on your trust in the people who have signed the key
(including, but not limited to, the key owner).  

'Trust' in a person is a property of your particular installation of
GnuPG.  Trust is a private value that only you have to know about and
refers to whether or not you trust the person's signature on a key to be
as good as your signature on a key, and the degree to which that trust
exists.  Initially, key owners have a trust value of 'unknown'.  You may
give them a trust value of 'none' if they are known to improperly sign
keys.  A value of 'marginal' means that they understand key signing and
perform it properly.  A value of 'full' means that they have an
excellent understanding of key signing and that you trust their
signature on a key as well as if you had signed the key yourself.  

By default, a key is considered valid if it is signed by at least one
person to whom you give full trust, or it is signed by at least three
people to whom you give marginal trust.  This can of course be
reconfigured, and a lower number of marginally trusted owners would
signify a smaller number of people who would have to conspire against
you to pass a key off as valid. 

Without the necessary trusted signatures, the key is not considered
valid.  This does not necessarily mean that the key does not belong to
whom you expect it to, but that the software is warning you that it has
no way of knowing.  Obviously, the web of trust is the weak point in
public key cryptography, but when used properly can introduce some level
of assurance into the situation.  

Allow me to illustrate the importance of key validity with an example.
Say that you have met someone on IRC and that she has helped you for a
long time with many systems administration issues.  She tells you that
she is going to send you a script that you should run as root on your
machine.  If you know this script to come from this person, you would
have no problem running it on your machine, due to your trust in her.
But, perhaps someone has previously hijacked the communication between
you and friend in which you obtained her public key.  Then, they could
have possibly altered the message to contain a harmful script and passed
it off as valid.  The end result is that you are harmed and that you
possibly blame your friend.  

If you had first validated the public key being used, this would have
been avoided.  You could have done this by signing the key yourself.
You also could have insured that the key was signed by at least one
other person to whom you have given full trust.  Lastly, you could have
insured that the key was signed by at least three key owners to whom you
have given marginal trust.  

In order to sign a public key with your own private key, you must be
absolutely sure that the key belongs to a person who is who they say
they are.  You should use a reliable method of communication to verify
the key fingerprint of the key before signing it with your own.  You may
obtain a key fingerprint by doing this:  

    gpg --fingerprint <key owner name>

For example, my key fingerprint is:  

    2231 DFF0 869E E3A5 885A E7D4 F787 7A2B C9C4 0C31

If you communicate with the key owner, perhaps in person, or over the
phone (if you know their voice), or over certified mail, you know them
to be who they say they are, and the key fingerprints match, then you
may sign the key.  You do this by issuing this command:  

    gpg --sign-key <key owner name>

In order to assign trust to a key owner, you must assign the owner a
value in your GnuPG trust database.  You do this by editing their key: 

    gpg --edit-key <key owner name>

Type 'trust' and then follow the directions.  

After all of this is done, if you trust someone fully to understand the
significance of key signing, you can thereby, via your web of trust,
validate all keys signed by them.  


VIII. Understanding The Need For Message Signatures

The first reason for message signatures is authenticity.  It is a
largely unknown fact that the From: header of email can be trivially
forged.  A quick glance can lead you to believe that the mail was sent
by someone who might not have had anything to do with the message.  A
signature will help you determine if the mail was really sent by who you
think it was sent by.  

The second reason for signatures is integrity.  Someone who has access
to any piece of mail that is waiting for you (perhaps at your ISP) can
change the message.  This could affect something as simple as where you
should meet someone to something as serious as which bank account you
should transfer money to.  A signature can tell you if the message was
modified between the sender and your mail client.  


IX. Understanding How Signatures Are Made

Signatures typically are attached to the message.  Detached signatures
that are placed in an alternate download location are possible, but are
not practical for something such as email, where all-in-one
communication is the goal.  The outdated standard for making attached
signatures was to paste it at the bottom of the message, but the new
standard involves an actual MIME attachment to the message.  Regardless,
Mutt can verify either style.  

The important thing to understand is that the signature for each piece
of mail is different and is based on both the sender's key and the
content of the message.  If all signatures from a person were the same,
then one could just copy the signature from a mailing list post and
start putting it on their own mail.  Therefore, the signature is based
partly on the contents of the data being signed.  

Another important point to note that has been brought up recently in
security forums is a weakness of signatures.  Because signatures sign
only the body of an email, a malicious hacker could intercept a message
from one person and redirect it to another while still keeping the
signature intact.  For example, if your boss emails a co-worker and says
"You're fired!", you could then send this message on to someone else who
would think it was addressed to them and see that the signature belongs
to their boss.  The approach to get around this is to always make it
clear in the message body to whom the message is addressed and to put
things in context so that they could not be misconstrued by a third


X. Understanding How Encryption Is Done

Aside from the obvious fact that the message is encrypted, an important
thing to note about encryption is that even the sender cannot read the
encrypted message.  Fortunately, Mutt has two ways around this.  There
is an option that lets you save a plaintext copy of your outgoing
messages when saving to a 'sent' folder (see Mutt's 'fcc_clear' option).
You may also configure Mutt to use GnuPG's '--encrypt-to' option to
additionally encrypt all encrypted mail to you so that encrypted mail in
your 'sent' folder can be decrypted by you.  Without one of these
options, only the intended recipient can decrypt the message that was
sent out, even if a copy resides in your 'sent' folder. 

In order to encrypt a message to someone, you need their public key.
Once you've got that, you name them as the recipient and the message is
encrypted in an (as of yet) unbreakable code.  

Remember that encryption alone does not guarantee authenticity, as
anyone with the recipient's public key can send them encrypted mail.
Adding a signature to encrypted mail ensures that it originated from you
and was encrypted by you.  


XI. A Practical Example of Manual Key Management

In order to understand what Mutt is going to do for you, you need to
know what happens behind the scenes.  In order to verify a signature or
encrypt a piece of mail for someone, you need their public key.  You can
either download it from a person's website or request it from a
keyserver, or perhaps the person will email it to you (by the way, Mutt
of course has a handy shortcut to let you get keys out of an email with
the Control-k keystroke).  A key looks something like this (below is my
public key):  

Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org


Once you've got the key in a file on your computer, to add it to your
keyring, or your store of available keys, you would do this:  

    gpg --import <key file>

GnuPG will take care of the rest.  The nice thing about the whole system
is that extraneous text before the beginning and ending markers is
ignored, so keys can be embedded with text files that contain other
information, and GnuPG will still be able to import the key(s) from
those files.  

You can verify that a key is now in your keyring by listing all of your

    gpg --list-keys

You can also list particular keys by key ID or a word from the owner's

    gpg --list-keys <owner's first name>

Please note that this is the bare minimum way to use public keys.  You
should also take into account your web of trust and later edit the trust
value for the key's owner and/or sign the key if you really want to rely
on communications using it.  


XII. A Practical Example of Manual Signing and Verification 

Take for example a sample piece of text:  

    Here is some sample text.  

If I saved this to a file called sample.txt and wanted to sign it before
distributing it, I would do this:  

    gpg --clearsign sample.txt

After entering my passphrase, this will output a new, signed version at

Hash: SHA1
Here is some sample text.
Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

With Mutt, your text can be signed automatically, the passphrase can be
cached for a customizable amount of time, and the recipient will get
your message along with a MIME attachment of the signature.  

In order to verify a signed file, I would do this:  

    gpg --verify sample.txt.asc

The output, providing I have the signer's (my own) public key, looks
like this:  

    gpg: Signature made Thu 16 Aug 2001 06:56:01 PM EDT using DSA key ID C9C40C31
    gpg: Good signature from "Justin R. Miller <justin@solidlinux.com>"

Mutt can automatically verify signatures, retrieving public keys if
necessary, and will show signed messages as just the message text with
some status bar info regarding the signature validity.  It looks almost
like regular mail, and you don't have to do a thing to verify the
message's integrity besides have the sender's public key (or have it
automatically fetched).  


XIII. A Practical Example of Manual Encryption and Decryption

In order to encrypt our file, we would run this:  

    gpg --encrypt --armor sample.txt

The '--armor' option causes the encrypted file to be outputted as text
instead of binary data.  After choosing the public key of the intended
recipient, an encrypted file might look like this:  

Version: GnuPG v1.0.6 (GNU/Linux)
Comment: For info see http://www.gnupg.org

With Mutt, you can just indicate that you would like to encrypt a
message, choose the intended recipient's public key from a menu, and the
message is sent without you ever having to see the encryption.  

Since I cannot decrypt the above file (as it wasn't intended for me), I
will just show the steps necessary to decrypt a file:  

    gpg --decrypt <encrypted file>

After entering my passphrase and if the message was intended for me, a
new file will be written containing the decrypted text.  

With Mutt, the passphrase can be cached and messages will automatically
be decrypted and displayed in the message view screen, along with a
brief indication of whether encryption and/or a signature was involved.  


XIV. Configuring Mutt For Use With GnuPG

In order to use Mutt with GnuPG, PGP support must be compiled in when
building Mutt (this happens by default).  Also, you need to add some
directives to your .muttrc (or source a file containing these
directives) which tells Mutt how to interact with GnuPG.  Here are the
commands that I use:  

set pgp_decode_command="gpg %?p?--passphrase-fd 0? --no-verbose --batch --output - %f"
set pgp_verify_command="gpg --no-verbose --batch --output - --verify %s %f"
set pgp_decrypt_command="gpg --passphrase-fd 0 --no-verbose --batch --output - %f"
set pgp_sign_command="gpg --no-verbose --batch --output - --passphrase-fd 0 --armor --detach-sign --textmode %?a?-u %a? %f"
set pgp_clearsign_command="gpg --no-verbose --batch --output - --passphrase-fd 0 --armor --textmode --clearsign %?a?-u %a? %f"
set pgp_encrypt_only_command="pgpewrap gpg --batch --quiet --no-verbose --output - --encrypt --textmode --armor --always-trust --encrypt-to 0xC9C40C31 -- -r %r -- %f"
set pgp_encrypt_sign_command="pgpewrap gpg --passphrase-fd 0 --batch --quiet --no-verbose --textmode --output - --encrypt --sign %?a?-u %a? --armor --always-trust --encrypt-to 0xC9C40C31 -- -r %r -- %f"
set pgp_import_command="gpg --no-verbose --import -v %f"
set pgp_export_command="gpg --no-verbose --export --armor %r"
set pgp_verify_key_command="gpg --no-verbose --batch --fingerprint --check-sigs %r"
set pgp_list_pubring_command="gpg --no-verbose --batch --with-colons --list-keys %r" 
set pgp_list_secring_command="gpg --no-verbose --batch --with-colons --list-secret-keys %r" 
set pgp_autosign=yes
set pgp_sign_as=0xC9C40C31
set pgp_replyencrypt=yes
set pgp_timeout=1800
set pgp_good_sign="^gpg: Good signature from"

Aside from the basic commands necessary to inter-operate with GnuPG,
these directives also tell Mutt to automatically sign all outgoing
messages using key ID 0xC9C40C31 (my key), to encrypt all encrypted mail
to me as well (for storage in my 'sent' folder, and to cache my
passphrase for a half hour.  


XV. Trying It All Out

Mutt should be ready to go at this point.  The first time you send a
message, Mutt will ask you for your passphrase, which it will then
cache, then it will sign all outgoing messages.  When you receive a
signed message, Mutt will use the sender's public key (fetching it if it
has to) to verify the signature.  When encrypting messages, it will ask
for your passphrase (if not cached) and will present you with a menu of
public keys that it believes match the intended recipient.  Lastly, when
decrypting messages, it will ask you for your passphrase if the cache
has expired or it hasn't been entered yet.  


XVI. Links For More Information

The Mutt E-Mail Client Home Page

The GNU Privacy Guard Home Page

The Mutt-i, GnuPG and PGP Howto

The International PGP Home Page

Why You Should Use Encryption


XVII. Contributors

I'd like to thank the following people for assistance in revising this

 - Dave Chapeskie, for many clarifications, corrections,
   recommendations, and security tips  

 - Thomas Roessler, for a very clear explanation of validity and trust  

I'd like to thank the following people for suggestions and feedback that
I may incorporate into a later revision of this document: 

 - Andrew McDonald
 - Rick Moen
 - Andy Smith

Lastly, I would like to thank you for reading this far!


XVIII. Feedback

I hope that this document has been of use to you.  Please let me know if
there is any way that I can improve it.  You can contact me via email at
justin@solidlinux.com, and I would of course prefer that you use
encryption when doing so using my public key, found elsewhere in this
document or at http://solidlinux.com/~justin/pubkey.asc.  

$Id: mutt-gnupg-howto,v 2002/03/04 00:03:18 incanus Exp $