MacGPG Step by Step

Important note!
This post is pretty out-of-date now. I am working on a newer one, that simplifies the following steps and discusses integration with keybase.

There is now an installer that will install the main GPG tools in one go. It installs GPG1 instead of GPG2, but for you and me, that doesn’t matter much (in fact, it doesn’t matter at all, according to the GPGMail guys – except GPG1 has fewer bugs). You can find it here: GPG Tools for Mac. The instructions for generating your key and using the mail plugin still apply, but you can ignore the “Install X” parts of the instructions.

I have had some issues trying to move from GPG2 to GPG1. At this time, I recommend you do NOT install GPG2. Use the above installer and get GPG1 along with the other tools. It’s easier and works better. If, like me, you have GPG2 intstalled already, I would advise sitting tight with what you have until I can figure out the best path to happiness.

Installing Gnu Privacy Guard (GPG) version 2 on a Mac is pretty simple, but when I did it I found that much of the information on how to do it is scattered around the Web. Some places had more detail than others, and I found myself going in circles looking for links to pages I knew I’d seen before.

In other cases, the explanations for simple ideas were so laden with jargon that the ideas came out seeming pretty complicated. Not ideal for someone getting up to speed on this stuff for the first time. I decided to create this little introduction to GPG along with really basic instructions to give enough information to allow a Mac user who has never seen the stuff before to get up and running.

A Brief Overview

This is a simplified version of how the system works. You can probably skip this section, but when we get to the part about sharing keys later, it might come in handy.

GnuPG is a system that allows you to protect your privacy by encoding your electronic files. One of the most important things to encrypt is email – in a perfect world every email message would be encrypted so only the intended recipient could read it. The way the system works is complicated (and clever), but think of it this way: you have a coder ring and a decoder ring. Messages encrypted with the coder ring can only be read by someone with the decoder ring. Now you give your friend the coder ring. In fact, you can give the whole world copies of your coder ring! Now anyone can send you secret messages. Since you’re the only one with the decoder ring, only you can read the messages. Everyone else just sees gobbledygook.

To reply to a message from your buddy, you use his coder ring, and only he will be able to decode it.

This seems backwards to most people at first – they expect to keep the coder ring secret, so they can send secret messages. But remember, it’s decoding that has to be kept private. Anyone can write a secret message to you, but only you can read it. If that just confused you, don’t worry about it. It will all work out.

In GPG terms, the coder ring is called a public key, while the decoder ring is called a private key. Those are actually better terms because the keys work in reverse as well. The private key is for things only you can do – read a secret message that has been sent to you, or sign a message you are sending to prove it’s really from you. We’ll go into that more later, if it turns out to matter.

Getting Started on your Mac

As I mentioned before, all this information is out there, but I didn’t find good beginner-level information all in one place. Please let me know if you hit snags in this process.

Step 1: Install the Core Software

Technically, this is the only thing you need to install. The rest of the steps are just to make MacGPG easier to use.

Important: See note above – there is a new installer that works better, but is not compatible with the version installed here. I will be updating these instructions shortly. At this time advise you to NOT install MacGPG2, but to use the simple installer linked to above.

Go to, and click on the big green “download” button. An installer will download. Double-click it. There are no surprises here; just go through the screens and type in your user password if you have one.

When you are done, you will see the Congratulations! message. Restart your computer. This will make sure that the various bits and pieces that were just installed are all running.

Your computer comes back to life and you wonder, “now what?” Nothing seems to have changed.

Step 2: Create Your Keys

Before you can use the software, you need to create your public and private keys. These are actually a matched pair of ginormous numbers. When your message is scrambled up with one of the numbers, the other can be used to unscramble it.

To perform this operation, you will have to type a command into the terminal. Don’t worry, this will be simple even if you’ve never used your terminal before. The hardest part might be finding Terminal (it’s in your Applications/Utilities folder). When you double-click Terminal a little window will open with a little blinking cursor. How quaint! How powerful!

NOTE: more detailed (but slightly out-of-date) instructions are here. I put a full transcript of a key-generating session at the bottom of this page, which might be the simplest way to get going quickly.

ANOTHER NOTE: It’s possible that GPG Keychain Access (installed in Step 4) can do this without you having to deal with the terminal. If you want to hold off with all this key-gen business until later and try GPG Keychain Access instead, you’ll probably be fine. I just haven’t tried it that way personally, so I’m going old-school here.

Type gpg --gen-key and press return. Stuff will happen! The easiest thing is to just accept the defaults for everything, by pressing return three times, then ‘y’ and return*.

After that you will be asked for some personal information. This is the stuff that will help you tell keys apart later. The first is your name. When people search for your key, what name are they likely to use? I put in “Jerry Seeger”.

Next comes email address. Use your real email address, because when people want to send you a message this is the main way they will find the right key to use. (You can add more addresses to the same key later.)

Finally it asks you for a comment: It really doesn’t matter what you put here; I think it’s mainly so you can tell your keys apart if you use more than one with the same name and email. On my first key I used “privacy is good”. In retrospect, I might have used something like “Jerry’s main key”.

Review the information. If it’s all correct, type “O” for “ok” and press return.

Here’s where one of the “features” of the Mac version pops up. Rather than type the passphrase into the same window you’ve been using, a different window pops up. Umm… thanks? Anyway, time to put in a passphrase. The passphrase should be more than just a simple password, but something you won’t forget. If you forget this passphrase, you are hosed. Something like “Have 1 Hippy Gnu Ear!$!” would be easy to remember but really hard to guess.

Things will happen, a warning may go by (no biggie), and your computer will be doing some serious number crunching. It actually helps this process if you do other things while this is going on (it helps with the random number generation).

Hooray! You have keys!

Um… now what?

Step 3: Install the Proper Email Plugin

GnuPG gets a lot easier to use if you install some helper software to get at its features without using the command line. The most important one is the email plugin.

If you use Apple’s, go to and download the version that matches your version of Mac OS X. Run the installer, and there you go. When you start Mail and create a new message, you’ll see you have two new options: Sign and Encrypt. When you sign a message, anyone with your public key can verify that the message is from you and hasn’t been tampered with. When you encrypt a message, you use someone else’s key to encode the message and only they will be able to read it.

Plugins for other email software can be found here.

I’ve decided to ALWAYS sign my messages. My main motive is to tell anyone who gets an email from me that I’m part of the PGP** club and they can send encrypted messages to me.

You’re good to go! Except… you need to get your friends’ keys, and you need to share your public key with others. I’m going to put that in a separate section so we can finish up with installing the rest of the helper bits first.

Step 4: Installing Other Helper Apps

Although aficionados of the command line scoff at such silliness, I like to use these helper apps that provide a GUI for the stuff I do most often. All these bits are found at

GPG Keychain Access 0.3.1b – has moved to github. (This is a newer version than I previously listed here, but with a lower version number. *sigh*) This will let you fiddle with your keys – making new ones, adding more email addresses to existing ones, and whatnot. Download the file, unzip if necessary, and drag GPG Keychain Access to your Applications/Utility folder (that’s where I put it, anyway).

NOTE: Your Mac came with a program called Keychain Access, with is totally separate from GPG Keychain Access. I look forward to the day when GPG uses the built-in keychain stuff on the Mac, but in the meantime you will have two programs with almost identical names.

GPGPreferences 1.2.2 – this is a preference pane that lets you fiddle with the most common preferences. I wouldn’t even know what those options were otherwise, so it was nice to have something to look at (and not change…) Download the dmg and if it doesn’t mount as a drive on your system automatically, double-click it. A window will open and you will see GnuPG.prefpane. Double-click that, say yes to installing it, then say “Please, do” to using utf-8. After that, you can poke around, but chances are you won’t be inclined to change much. (We’ll go into the Key server later.)

GPGFileTool 1.0.2 – emails aren’t the only things to protect. This little utility allows you to encode files on your hard drive. There are other products that do this more conveniently, but what the heck, it’s here and it’s free. I put it in Utilities, along with GPG Keychain Access.

GPGDropThing 0.4.3 – sometimes, for whatever reason, GPGMail doesn’t decode the message correctly. While we wait for the GPG wizards in their tower to fix things, this little utility comes in handy. Just drop the encoded text in here and choose ‘decrypt’ and you’re good to go.

There are a few other bits and pieces at the above address, but they didn’t seem as useful.

Step 5: Getting Rolling with Your New Stuff!

It takes two to pass a secret message. The challenge now is to make your public key truly public, and to get other people’s keys. There are a bunch of servers around the world that keep a big ‘ol database of keys. When you add your key to one of those servers, it will fairly quickly be copied to all the others.

NOTE: These instructions assume you have installed GPG Keychain and GPGPreferences in step 4. You can also do the following steps using commands in the terminal, but I won’t be covering that here. You can find the full instructions here.

To get started, open your system preferences, choose GnuPGP from the bottom row (installed in step 4), and under Key Server choose any of the options. (I used If you did not install GPGPreferences, I’m pretty sure you can choose a server directly through GPG Keychain Access.

Next, to upload your key, open GPG Keychain Access, select your key, and under the Key menu select Send to Keyserver. The terminal will open up, to tell you it’s sending the thing, but no action is required on your part. Now anyone can find your public key! Hooray! They can send you secret messages!

You can also use the same servers to get other people’s keys, which is handy. There’s a catch, however. How do you know the key on the server really came from that person? There are two ways you can confirm the validity of a key: confirm it directly with the help of the other person, or rely on your web of trust. The web of trust is a simple idea that is difficult to explain, so we’ll leave it for another section. Let’s talk about verifying the key directly.

The simplest way is to get the “fingerprint” for the key directly from the key’s owner. For instance, the fingerprint for my key is here on this Web site, so folks can come here, get that number and compare that fingerprint with the fingerprint of the key they have in their sweaty hand. If the fingerprints match, we’re good to go.

Let’s go with a concrete example. The GPG documentation could really use more concrete examples.

Let’s say for a moment that you want to send me a message. Because you’re a good citizen you encrypt all your messages, no matter what’s in them. You open up your email software, type my address in the “to:” field, and then check the “encrypt” option. In the popup list next to it you choose “download” and your software checks your favorite keyserver and finds a key that matches my address. Hooray. But is it the right key? If your system has never seen the key before, it will ask you whether you trust the new key.

Do you trust that key? Not yet. Anyone could have put that key up there. The world is filled with liars and cheats. Happily, you can come to this Web site and find my fingerprint and compare. Unless we’re passing nuclear secrets, that’s probably assurance enough that the key you have is mine. Otherwise I could send you the fingerprint in a letter, or read it out to you over the phone. Or maybe you could send me a message using the key, and I could phone you to confirm that I got it, if you could reliably identify me over the phone. There are lots of ways. keybase is a new system to help make this process smoother, but it’s still in its infancy.

Once you’re convinced the key is valid, you approve it for your system and we’re good to go. To do this with GPG Keychain access, select the key and under the Keys menu choose “Sign”.

Seems like kind of a hassle, though, to do that with everyone with whom you exchange emails. This is where the web of trust comes in.

NOTE: Actually, it seems that GPGMail is set to trust keys by default. While this is convenient, it’s also a little dangerous. Chances are that if you’re reading this you’re not passing state secrets or anything, so that’s OK. It’s still a good idea to verify keys and sign them.

The Web of Trust

Going back to our example, you have my key and you have confirmed that it is valid. We are exchanging messages, and then I suggest we include Alice in our conversation. Rather than go through the hassle of contacting Alice and confirming her key, you can say, “I know Jerry is careful; if he says this key is good, then I believe him.” You load the key and your system sees that I have endorsed it and off you go.

The important thing to remember is that you’re not deciding how much you trust Alice – she’s a stranger. You’re deciding how much you trust me.

If you only sort of trust me to be diligent confirming keys, you can set your software to automatically validate a key if enough of your sort-of-trusted friends vouch for it. In either case, you don’t have to go through any further hassles.

That’s pretty much all there is to it, but there are of course some details to make that work. The first is that I have to have a way to mark other people’s keys with my endorsement. If I download someone’s key from a server and then confirm that it is good, I can put my own signature on the key and (with the owner’s permission) copy that key back up to the servers. Any time someone else downloads the key after that, they can see that I confirmed its validity. Depending on how much they trust me, they can choose whether or not to trust the key.

The second detail is that you have to tell your system that you trust me. You do that by putting a note on my key in your keychain. When your system encounters a key endorsed by me, it will look on your keychain to find out just what you think of me.

Naturally, you would only ever endorse keys that you personally confirmed carefully.

To expand this web of trust, there are events called “key-signing parties” where a bunch of peers all pass around and endorse each other’s keys. Then the entire group can speak freely without worries about eavesdroppers.


That was a lot of stuff we just went through, but the good news is that the first four steps are done and you’ll never have to deal with them again, while there’s no hurry getting comfortable with the web of trust. It will happen gradually, and eventually the danger of some asshole taking one of your messages and using an excerpt out of context is greatly reduced. That alone makes the hassle worth it, don’t you think?



* MacGPG2 has an option for what kind of key to create that does not appear in any of the other documentation. It’s the default. Does that mean it’s the best? Heck if I know. I actually went with option (2), the option that all the other documentation recommends.

** I didn’t go into the GPG – PGP – OpenPGP alphabet soup. GPG used OpenPG, which is a standard. PGP and GPG work together, so don’t worry about all the acronyms.

Appendix 1

The following is copied from the terminal after going through a sample key-generating session. What I typed is in red. If I only hit the return key, I indicated that with [return].

iJer:ams Jerry$ gpg --gen-key
gpg (GnuPG/MacGPG2) 2.0.14; Copyright (C) 2009 Free Software Foundation, Inc.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Please select what kind of key you want:
(1) RSA and RSA (default)
(2) DSA and Elgamal
(3) DSA (sign only)
(4) RSA (sign only)
Your selection? 2
DSA keys may be between 1024 and 3072 bits long.
What keysize do you want? (2048) [return]
Requested keysize is 2048 bits
Please specify how long the key should be valid.
0 = key does not expire
= key expires in n days
w = key expires in n weeks
m = key expires in n months
y = key expires in n years
Key is valid for? (0) [return]
Key does not expire at all
Is this correct? (y/N) y

GnuPG needs to construct a user ID to identify your key.

Real name: Jerry Seeger
Email address: [email protected]
Comment: temp key
You selected this USER-ID:
"Jerry Seeger (temp key) "

Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key.
[At this point a new window opens up for the passphrase and confirmation]

We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: WARNING: some OpenPGP programs can't handle a DSA key with this digest size
We need to generate a lot of random bytes. It is a good idea to perform
some other action (type on the keyboard, move the mouse, utilize the
disks) during the prime generation; this gives the random number
generator a better chance to gain enough entropy.
gpg: key AC89613D marked as ultimately trusted
public and secret key created and signed.

gpg: checking the trustdb
gpg: 3 marginal(s) needed, 1 complete(s) needed, PGP trust model
gpg: depth: 0 valid: 2 signed: 0 trust: 0-, 0q, 0n, 0m, 0f, 2u
pub 2048D/AC89613D 2010-08-16
Key fingerprint = 4C1D F977 02C0 179E 746E C973 8008 76A8 AC89 613D
uid Jerry Seeger (temp key)
sub 2048g/A13E39FD 2010-08-16

Apendix 2

How to tell if MacGPG2 is installed and running correctly. If you are having problems, the first step is to restart your machine. After you restart, type the following five commands in the terminal and look at the results. They should be similar to what I have here. Commands to type are in red, the responses are black:

iJer:~ Jerry$ gpg2 --version
gpg (GnuPG/MacGPG2) 2.0.14
libgcrypt 1.4.5
Copyright (C) 2009 Free Software Foundation, Inc.
License GPLv3+: GNU GPL version 3 or later
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.

Home: ~/.gnupg
Supported algorithms:
Pubkey: RSA, ELG, DSA
Hash: MD5, SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
Compression: Uncompressed, ZIP, ZLIB, BZIP2
iJer:~ Jerry$ which gpg2
iJer:~ Jerry$ ls /usr/local/libexec
gnupg-pcsc-wrapper gpg-preset-passphrase gpg2keys_curl gpg2keys_hkp
gpg-check-pattern gpg-protect-tool gpg2keys_finger gpg2keys_ldap
iJer:~ Jerry$ gpg-agent
gpg-agent: gpg-agent running and available
iJer:~ Jerry$ ps waux | grep gpg-agent
Jerry 5621 0.0 0.0 614468 944 ?? Ss 6Aug10 0:51.96 /usr/local/bin/gpg-agent --daemon --use-standard-socket --write-env
Jerry 37169 0.0 0.0 2435468 0 s004 R+ 5:52PM 0:00.00 grep gpg-agent

10 thoughts on “MacGPG Step by Step

  1. As of this writing, there is an annoying bug in GPGMail 1.3.0 – When installed with MacGPG2, some of the preferences don’t work. The most annoying is the preference for your Mac to remember your passphrase. As a result, you will end up typing your passphrase pretty often.

    You can get around this problem by using an older version of MacGPG, downloaded from here.

    I have not personally installed that version. If you’ve already installed MacPGP2, you will need to remove it first, which is not trivial (that’s why I haven’t done it).

    I did try to download the latest source for GPGMail to look into fixing the bug myself, but build I checked out (NOT the stable version 1.3.0 download) crashed instantly and I didn’t want to start with something that unstable.

  2. Thanks for the great help!
    Unfortunately you are right about saving the passphrase in the keychain. I just assume it’s gonna be fixed pretty soon :-)
    I can also recommend using the “By default, use OpenPGP/MIME” option. That way the signature is detached (in an attachment) and you won’t have the strange start and end of the signed message in the Email.

  3. Thanks a lot! This was really easy, a lot more so than the time I tried it on Win XP with GPG and Thunderbird/Outlook.

    Using OpenPGP/MIME does in fact remove the signature from the message body and moves it into an attachment, then again some Email clients won’t show the attachment (in my case, Postbox, a Thunderbird derivate) – and then what’s the point.

  4. Glad I wrote this up — My latest OS upgrade broke GPGMail. I followed the link in step 3 above, downloaded the new version, restarted an all was well. (Except for the aforementioned failure to respect user preferences.)

    • Thanks! I’ll be updating the above instructions to use gpg1 — once I get it working. Right now nothing is working. I suspect GPG Keychain access is unhappy about there being both GPG1 and GPG2 installed.

  5. I have a situation for you.

    We have a department Key. its a public/private keypair with a password. The data comes encrypted from another department, we decrypt it. I’m using GPG tools for Mac.

    I have a user who can decrypt all the files. I have another user who can decrypt any file older than 2 weeks old. No error message just Unable to decrypt. I’m not very conversant in GPG, and I can’t find anything to tell me why this wouldn’t work. Could you shed some light on the subject?

Leave a Reply

Your email address will not be published. Required fields are marked *