Setting up Keybase and GPG Tools (Mac)

What are GPG Tools?

GPG, or GNU Privacy Guard, is a replacement for Symantec’s PGP cryptographic software suite and allows users to encrypt sensitive information. Specifically, GPG Tools includes a utility that integrates with Apple Mail, a GPG Keychain to manage OpenPGP keys, and a command line tool (which I will be using below).

What is Keybase?

Keybase is an identity management service allowing users to manage keys, social media accounts, and devices. The idea is that when you meet someone online and want to exchange secure messages or files with them, you will want some way to establish the other party is who they say they are. Keybase has also created their own file system, which encrypts everything in their mounted drive. It’s a new feature and definitely worth reading more about here.

It’s worth noting that while Keybase does work with GPG and does have a relatively slick CLI, the Keybase CLI does lack equivalents to gpg --list-keys and gpg --export.

Currently Keybase is in alpha – so that means you need an invite or you can join the wait queue.

Digging Deeper: Key Caveats

Make sure you read Keybase’s privacy policy. I’m sure a lot of us are guilty of "leafing" through privacy policies and usage agreements; however, considering that Keybase’s purpose is to store sensitive information you might want to be aware of the what/where/how they collect and store data. Some highlights:

Probably obvious data collection, usage, and sharing:

  • The information you provide when signing up, i.e. the name you provide, your location, etc., is all stored. The information you put in your profile, including the names of the accounts you choose to verify, are publicly visible.
  • Data may be shared to comply with the law after receiving a request via a lawful process.
  • Data may be shared as a result of a business transaction, such as a corporate restructuring or merger.
  • Keybase is not responsible for any information you choose to share with third parties. e.g. If you share data with Twitter, it is bound by Twitter’s privacy policy not Keybase’s.

Some potentially less obvious collection, usage, and sharing:

  • Usage information is automatically collected and does not appear to be disable…able. So Keybase gathers and stores your IP address, host computer preferences, URL of the site that referred you to the service, how you interacted with the Keybase UI, and how long you were logged in for. This information is stored in logs that "may persist for an indefinite period."
  • "We may disclose any information, including your Personal Information and any other information or data collected, stored or processed on our servers, if required to do so by law or in the good-faith belief that such action is necessary…to protect the personal safety of Keybase employees, customers, or the public." I read "good faith" as them asking me to rely on them to Do No Evil with my data, which you may or may not want to do depending on what types of secure information you are interested in sharing.

Since the privacy policy is subject to change, make sure you read the latest version when you sign up and keep your knowledge of it up-to-date.

How to Setup Keybase and GPG

Signup for Keybase with either your invite or when your lucky # is drawn from the queue. When you choose your name, choose with caution. Remember, Keybase is an identity management service, which means that:

  1. You cannot change your username later, unless you open a new account and delete the old one which brings me to the next point:
  2. Once a user name is used, it cannot be reused. Even if the account has been deleted.

To clarify #2: this means if you delete your account, the username does not re-enter the free pool. It is unavailable forever. This makes sense, since you wouldn’t want to delete your account and then have someone else come along and pretend to be you. As with all things security: be aware, take care!

Moving along.

Installing Keybase and GPG Tools

You’ll need to install GPG Tools and Keybase. The GPG Tools suite is available on their site for Macs. For Keybase, you can either use the Keybase installer which installs an app and the CLI utility, or you can use Homebrew: brew install keybase. Note that you may need to run brew update && brew upgrade keybase. I ultimately used the installer so I could have the app as well to explore later.

Generating your public PGP Key for Keybase

Now that you have your Keybase account and CLI tools, you’ll need to generate a public PGP key so you can encrypt/decrypt files and messages. You can do this either with the Keybase CLI or GPG. In my case, I went the GPG route:

==[]=[ 15:34:05 ]=[  [email protected]  ]=[ ~     ]=[]==
$ gpg --gen-key
gpg (GnuPG/MacGPG2) 2.0.30; Copyright (C) 2015 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? 1
RSA keys may be between 1024 and 4096 bits long.
What keysize do you want? (2048) 4096
Requested keysize is 4096 bits
Please specify how long the key should be valid.
         0 = key does not expire
      <n>  = key expires in n days
      <n>w = key expires in n weeks
      <n>m = key expires in n months
      <n>y = key expires in n years
Key is valid for? (0) 0
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: Quintessence
Email address: myemail[at]
You selected this USER-ID:
    "Quintessence <myemail[at]>"
Change (N)ame, (C)omment, (E)mail or (O)kay/(Q)uit? O
You need a Passphrase to protect your secret key.
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.
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 PSUEDOPUB 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
gpg: next trustdb check due at 2018-08-19
pub   4096R/PSUEDOPUB 2016-08-24
      Key fingerprint = <REDACTED>
uid       [ultimate] Quintessence <myemail[at]>
sub   4096R/PSEUDOSUB 2016-08-24
==[]=[ 15:37:11 ]=[  [email protected]  ]=[ ~     ]=[]==
$ gpg --list-keys
pub   2048D/PGPPUB  2010-08-19 [expires: 2018-08-19]
uid       [ultimate] GPGTools Team <team[at]>
uid       [ultimate] GPGMail Project Team (Official OpenPGP Key) <gpgmail-devel[at]>
uid       [ultimate] GPGTools Project Team (Official OpenPGP Key) <gpgtools-org[at]>
uid       [ultimate] [jpeg image of size 5871]
sub   2048g/PGPSUB1 2010-08-19 [expires: 2018-08-19]
sub   4096R/PGPSUB2 2014-04-08 [expires: 2024-01-02]
pub   4096R/RVMPUB 2014-10-28
uid       [ unknown] Michal Papis (RVM signing) <mpapis[at]>
pub   4096R/PSUEDOPUB 2016-08-24
uid       [ultimate] Quintessence <myemail[at]>
sub   4096R/PSEUDOSUB 2016-08-24

To export the public key for Keybase:

==[]=[ 15:42:55 ]=[  [email protected]  ]=[ ~/.gnupg     ]=[]==
$ gpg -a --export PSUEDOPUB
Comment: GPGTools -

Make sure you use the -a flag for ASCII, otherwise you’ll get binary output dumping to your terminal. Everyone’s favorite experience, amirite?

Copy/paste the key block into Keybase and choose "command line with keybase" when prompted for how you would like to sign your public key. Keybase will display the appropriate command to sign the public key, but first you will need to log into the Keybase API on your laptop using the Keybase CLI. To do this, you will use the same password you use to log into the Keybase website. When you initially log in with the Keybase ClI you will be prompted to generate a paper key, as below:

==[]=[ 15:55:57 ]=[  [email protected]  ]=[ ~/.gnupg     ]=[]==
$ keybase login
Your keybase username or email address: quintessence
Enter a public name for this device: FingerSkillet
During Keybase's alpha, everyone gets a paper key. This is a private key.
  1. you must write it down
  2. the first two words are a public label
  3. it can be used to recover data
  4. it can provision new keys/devices, so put it in your wallet
  5. just like any other device, it'll be revokable/replaceable if you lose it
Your paper key is
Write it!
Have you written down the above paper key? [y/N] y
Excellent! Is it in your wallet? [y/N] y
✔ Success! You provisioned your device FingerSkillet.
You are logged in as quintessence
  - type `keybase help` for more info.

Now that you have logged in, you can proceed:

==[]=[ 16:26:00 ]=[  [email protected]  ]=[ ~/.gnupg     ]=[]==
$ keybase pgp select <REDACTED>
#    Algo    Key Id             Created   UserId
=    ====    ======             =======   ======
1    4096R   <REDACTED>             Quintessence <myemail[at]>
Choose a key: 1
▶ INFO Bundle unlocked: <REDACTED>
▶ INFO Generated new PGP key:
▶ INFO   user: Quintessence <myemail[at]>
▶ INFO   4096-bit RSA key, ID <REDACTED>, created 2016-08-24
▶ INFO Key <REDACTED> imported

Generating the PGP key with Keybase

The other way to generate your PGP key is with the Keybase CLI, using keybase pgp gen. When you do, you will be given the option to upload the (encrypted) secret key to Keybase, e.g.:

==[]=[ 14:45:05 ]=[  [email protected]  ]=[ ~     ]=[]==
$ keybase pgp gen
Enter your real name, which will be publicly visible in your new key: Quintessence
Enter a public email address for your key: myemail[at]
Enter another email address (or <enter> when done):
Push an encrypted copy of your new secret key to the server? [Y/n]

Depending on your level of paranoia, putting a copy of the secret key on the Keybase server might be asking a bit much. Personally, this behavior is a reason in favor of generating keys with gpg, since Y is the default action.

Note: When you generate a key with keybase pgp gen it will appear in your GPG keyring.

Verifying an account with the CLI

Accounts can be verified using either the web UI or using the Keybase CLI. For the latter:

==[]=[ 16:31:42 ]=[  [email protected]  ]=[ ~/.gnupg     ]=[]==
$ keybase prove github quintessence
Please publicly post the following Gist, and name it
### Keybase proof
I hereby claim:
  * I am quintessence on github.
Check Github now? [Y/n] Y
▶ NOTICE Success!
==[]=[ 16:33:46 ]=[  [email protected]  ]=[ ~     ]=[]==
$ keybase prove hackernews quintessence
Please edit your HackerNews profile to contain the following text. Click here:
[ my public key: ...
Check HackerNews now? [Y/n] Y
▶ NOTICE Success!

Notice when you are proving that you are a user you are proving that you can somehow post as that user. In the case of GitHub, that means creating a public Gist. For other sites, e.g. Twitter and Reddit, you create a tweet/post. An example of a more complete profile is that of one of my coworkers here at S&W, James Hunt:

jhunt keybase profile

Following a user

You can see above that jhunt is already following me on Keybase. If I want to follow him as well, I can do so via the command line using his Keybase username:

==[]=[ 15:27:25 ]=[  [email protected]  ]=[ ~     ]=[]==
$ keybase follow jhunt
▶ INFO Identifying jhunt
✔ public key fingerprint: 2BA0 1C9D B438 A64F 214C D2D3 E7B1 C84A EDE5 75A0
✔ admin of DNS zone found TXT entry keybase-site-verification=v_ja_-Bvv9kxVH8l0JKdX_yCTFw4TlsZ2bFXoz4g9M0
✔ admin of DNS zone found TXT entry keybase-site-verification=QQg_TcUz22MGcRgb5DOcBIzsndgBpsuMZmhU7hQ7jes
✔ admin of DNS zone found TXT entry keybase-site-verification=qfh_K7mBbkb6JP3WrRLyZiu5bWz8jYCyEHwWopfdPDM
✔ "filefrog" on reddit:
✔ "iamjameshunt" on twitter:
✔ "jhunt" on github:
Is this the jhunt you wanted? [Y/n] Y
Publicly follow? [Y/n] Y

I can now see that he is both following me and I am following him using the Keybase CLI:

==[]=[ 15:59:40 ]=[  [email protected]  ]=[ ~     ]=[]==
$ keybase list-followers
==[]=[ 15:59:46 ]=[  [email protected]  ]=[ ~     ]=[]==
$ keybase list-following

I can also see that I’m following him now using the Keybase web UI:

following jhunt on keybase

Why follow other users?

Following users cuts out a couple steps when you wish to send encrypted information. For example, let’s say I wanted to send jhunt the following message:

keybase encrypt jhunt -m "Check out my blog post!"

If I wasn’t already following jhunt, the CLI would give me the same manual verification process to ensure that the jhunt it found was the jhunt that I intended to encrypt the message for. When I started following jhunt, Keybase created a signed snapshot of the identity. So now when I encrypt the above message, it uses the signed snapshot instead and doesn’t prompt me to verify the user.

For Keybase, following users also helps establish each user’s web of trust. When I started following jhunt I verified that I knew him. The more people that follow jhunt over time lends credibility to the Keybase jhunt user being matched with the correct person. Keybase talks about this a bit more in their doc on following users.

Key Deletion/Revocation

Keys are removed from the Keybase client using keybase drop '<KEY>'; however, this does not remove the key from your GPG keyring. Since keys generated with the Keybase CLI are stored in the GPG keyring, regardless of whether you used keybase or gpg to generate the key you will need to revoke the key on the GPG side as well or else the generated key will remain in your GPG keyring.

Spread the word

twitter icon facebook icon linkedin icon