GPG authentication

From bitcoin-otc wiki
Jump to: navigation, search

You can, and should, create a GPG-key-based identity with the bot. This gives you a verifiable and exportable identity on the order book and the rating system.

Third-party guides

The guide on this page is the authoritative one, but some enterprising folks have made prettier ones, with pictures and all. In the future, we hope to have some videos as well. This section has a list of such guides.

IRC / GPG Preface

IRC is a protocol for Internet text messaging in real-time. It's been around since the 80's and is still a popular choice of chat protocol today. #Bitcoin-OTC is an IRC 'channel', or 'chat room'. On IRC there are bots, or automated programs that perform a specific function. 'Gribble' is a bot in #bitcoin-otc that handles the ratings/trust system and other useful Bitcoin related functions.

GPG is an encryption and decryption program that provides cryptographic privacy and authentication for data communication. In Bitcoin-OTC's case, we use it for channel authentication to 'gribble', our channel ratings/trust bot.

Creating a GPG key

If you don't already have GPG on your system, you can download the source or binaries for many operating systems here.

If you are new to GPG, you will need to create a key, then upload it to a keyserver, before you're able to identify to the bot. First, generate the key by running, in a terminal (or command prompt):

gpg --gen-key

I recommend choosing the 4096 bit "RSA and RSA" key type. This is usually the first option in the list. On versions of gpg 1.4.9 and earlier, option 1 is "DSA and Elgamal" - so choose that one if you are using an older version. I also recommend not setting an expiration date. (If you do set the expiration date, remember to extend it regularly.)

Note the key id for generated pubkey. You need the 16 digit pubkey id for registering with the bot, you can get it by running the following command in a terminal:

gpg --list-keys --keyid-format long

Among the lines of output, you will see one looking like this:

pub   4096R/46ED38A2A668A578 2011-02-18

The key id is the 16 digits following the slash.

Now, upload your public key to some keyservers:

gpg --send-keys --keyserver pgp.mit.edu YOURKEYID
gpg --send-keys --keyserver subset.pool.sks-keyservers.net YOURKEYID

Note: any keyserver will work, but these are used by gribble to search for keys, so using these will reduce the time needed for gribble to discover your key.

subset.pool.sks-keyservers.net automatically resolves to a suitable keyserver see about keyserver pool

And that's all there is to it!

For a more detailed introduction to gpg, explore this tutorial.

Safeguarding your key

Your GPG key is your identity in the online world. Keep your private key safe from both destruction, and leakage to others. Use a strong passphrase on your key, and make a backup offline and/or offsite. The file containing your private keys is secring.gpg, and the file containing your public keys is pubring.gpg. Guard them similar to how you would your bitcoin wallet. Just as importantly - do not forget your passphrase, as that is tantamount to losing access [forever] to your key. Either write it down in a secure location, such as a notepad in your safe, or an encrypted password storage application.

Encryption-based authentication via GPG key with the bot

If you haven't yet registered your key with the bot, follow the registration procedure below. Otherwise, skip to the next section.

GPG registration

Note: if you have already registered using Bitcoin address authentication, use the 'echangekey' command to add a GPG key to your account.

To register the key, you will create an account with the bot with the gpg eregister command. The command takes the following arguments:

  • nick: your username in the bot's GPG database. It doesn't have to be the same as your irc nick, nor does it have to have any relationship to the name on your GPG key. For convenience, most people choose their IRC nick here.
  • keyid: your 16-digit gpg key id of your pubkey (the last 16 digits of your key fingerprint).

The bot will try retrieving your key from subset.pool.sks-keyservers.net and pgp.mit.edu.

By default, gpg --list-keys returns 8-digit ID's. You can find your 16-digit gpg key id by running:

gpg --list-keys --keyid-format long

You should see a line similar to

pub   2048R/81898844A1BF37D6 2011-03-06

where 81898844A1BF37D6 is the key ID that the bot needs.

So you might run the following, on IRC, to register with the bot:

;;gpg eregister BobJones 81898844A1BF37D6

Now complete your registration by decrypting your one time password.

GPG authentication

If you have already registered (see section above) you do not need to register again, instead just use the gpg eauth command, and supply it with your registered username as the only argument. For example:

;;gpg eauth BobJones

Now complete your authentication by decrypting your one time password.

One time password

The bot will respond to your registration/authentication request with a URL pointing to an encrypted document containing your one time password (OTP).

<gribble> Request successful for user <yourname>. Get your encrypted OTP from http://bitcoin-otc.com/otps/665FC11DD53E9583

Your task now is to decrypt the message. Visit the link provided, copy the encrypted message (the entire content of the page - so using keyboard shortcuts, you could hit Control-A, to select all, then Control-C, to copy), then run "gpg --decrypt" command (yes, actually press enter to run the command, before pasting the encrypted message) and paste in the encrypted message. If gpg prompts you for your passphrase, type it in and press enter.

At this point, if you are on Linux, press Control-D to terminate input. If on windows, press Enter, Control-Z, Enter to terminate input. Gpg will spit out the decrypted OTP. It will look something like this:

freenode:#bitcoin-otc:6132ffd1c3c4468e40303d844f3e30661bc34617054f7cc5e3fa03c8b41c376e

Now, supply the OTP to the bot through the gpg everify command. Example:

;;gpg everify freenode:#bitcoin-otc:6132ffd1c3c4468e40303d844f3e30661bc34617054f7cc5e3fa03c8b41c376

Once your OTP is verified, you will remain authenticated until you quit IRC, or leave the #bitcoin-otc channel, or if the bot gets disconnected from IRC. If you want to manually unauthenticate, use the gpg unauth command.

Sample session

The sample sessions below will give you an instant understanding of how this works.

Registration

The session is for registration by Alice.

<alice> ;;gpg eregister alice 665FC11DD53E9583
<gribble> Request successful for user alice. Get your encrypted OTP from http://bitcoin-otc.com/otps/665FC11DD53E9583

Now, Alice visits the link, copies the encrypted message, then runs "gpg --decrypt" command (yes, actually press enter to run the command, before pasting the encrypted message) and pastes in the encrypted message. She then enters her password if prompted.

At this point, if she is on Linux, Alice presses Control-D to terminate input. If on windows, she presses Enter, Control-Z, Enter to terminate input. Gpg will spit out the decrypted OTP for her to use. It will look something like this:

freenode:#bitcoin-otc:6132ffd1c3c4468e40303d844f3e30661bc34617054f7cc5e3fa03c8b41c376e

On a system with wget (mac, linux), Alice can save herself some trouble by running this command to automatically retrieve the url and pass it to gpg decryption:

wget -O - http://bitcoin-otc.com/otps/665FC11DD53E9583 | gpg --decrypt

Now Alice uses her OTP to finalize verification:

<alice> ;;gpg everify freenode:#bitcoin-otc:6132ffd1c3c4468e40303d844f3e30661bc34617054f7cc5e3fa03c8b41c376e
<gribble> Registration successful. You are now authenticated for user 'alice' with key 665FC11DD53E9583

Authentication

If Alice is already registered, and is coming in to log in again, she starts by running the following command on IRC:

;;gpg eauth alice

Then follows all the same steps as in the section above.

Helper scripts

Making a script is made easier by the fact that your OTP url remains the same - it is simply "bitcoin-otc.com/otps/YOURKEYID".

Shell

Linux

If you have xclip, just run the following:

wget -q -O - http://bitcoin-otc.com/otps/YOURKEYID | gpg -q --output - --decrypt | xclip -i

Enter passphrase if prompted, and the OTP will be in your clipboard, ready to paste.

Similarly you can use

echo -n ';;everify' `curl -4 http://bitcoin-otc.com/otps/YOURKEYID |gpg|tr -d '\n'`|xclip

to get the full everify command in your clipboard/selection.

If you don't have xclip, run the following:

wget -q -O - http://bitcoin-otc.com/otps/YOURKEYID | gpg -q --output - --decrypt

then copy the OTP from the terminal.

Mac

Run the following:

curl http://bitcoin-otc.com/otps/YOURKEYID | gpg -d | pbcopy

Enter passphrase if prompted, and the OTP will be in your clipboard, ready to paste.

Windows Powershell

powershell .\wget.ps1 "http://bitcoin-otc.com/otps/YOURKEYID" -Passthru | gpg -q --output - --decrypt | clip

Enter passphrase if prompted, and the OTP will be in your clipboard, ready to paste.

Windows Batch

  • Install GNU Wget binary
  • Run the following, or save as a .bat file and run:
wget -q -O - http://bitcoin-otc.com/otps/YOURKEYID | gpg -q --output - --decrypt

Then copy the OTP from the terminal.

(may need to provide full path to the wget and the gpg binaries, if they're not in your default search path.)

IRC client plugins

Signature-based authentication via GPG key with the bot

If you haven't yet registered your key with the bot, follow the registration procedure below. Otherwise, skip to the next section.

GPG registration

Note: if you have already registered using Bitcoin address authentication, use the 'changekey' command to add a GPG key to your account.

To register the key, you will create an account with the bot with the gpg register command. The command takes the following arguments:

  • nick: your username in the bot's GPG database. It doesn't have to be the same as your irc nick, nor does it have to have any relationship to the name on your GPG key. For convenience, most people choose their IRC nick here.
  • keyid: your 16-digit gpg key id of your pubkey (the last 16 digits of your key fingerprint).

The bot will try retrieving your key from subset.pool.sks-keyservers.net and pgp.mit.edu.

By default, gpg --list-keys returns 8-digit ID's. You can find your 16-digit gpg key id by running:

gpg --list-keys --keyid-format long

You should see a line similar to

pub   2048R/81898844A1BF37D6 2011-03-06

where 81898844A1BF37D6 is the key ID that the bot needs.

So you might run the following, on IRC, to register with the bot:

;;gpg register BobJones 81898844A1BF37D6

GPG authentication

If you have already registered (see section above) you do not need to register again, instead just use the gpg auth command, and supply it with your registered username as the only argument. For example:

;;gpg auth BobJones

Challenge-response

The bot will respond to your registration/authentication request with a random challenge string. You must clearsign a message containing the challenge string (see example below), and post it somewhere on the web that the bot can retrieve it from. I recommend using http://pastebin.com/ but you can use any pastebin of your choice, as long as it retains the unmodified clearsigned message somewhere in page source. Once you have that posted, supply the url to the bot with the gpg verify command, and supply the paste URL as argument.

The bot will verify your signature and authenticate you. You will remain authenticated until you quit IRC, or leave the #bitcoin-otc channel, or if the bot gets disconnected from IRC. If you want to manually unauthenticate, use the gpg unauth command.

Sample session

The sample session below will give you an instant understanding of how this works.

Registration

The session is for registration by Alice.

<alice> ;;gpg register alice 665FC11DD53E9583
<gribble> Request successful. Your challenge string is: freenode:#bitcoin-otc:cd6e049073b114975c6112d38eb1ecc2cbb3f116b9ac8366d3288d6b

At this point, Alice generates a clearsigned message. The simplest way is to open a shell (or command prompt), and try the following command:

echo freenode:#bitcoin-otc:cd6e049073b114975c6112d38eb1ecc2cbb3f116b9ac8366d3288d6b | gpg --clearsign

Then paste the resulting clearsigned message, including the cleartext header, into a pastebin of your choice. It should look similar to this:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

freenode:#bitcoin-otc:cd6e049073b114975c6112d38eb1ecc2cbb3f116b9ac8366d3288d6b
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)

iEYEARECAAYFAk1z9CQACgkQZl/BHdU+lYOIMwCfTdS0UOJ93KqzaYHF6CqLCr68
buIAoJQcEgQ9EJrPpxGREjN8yRkuKCfD
=XuYu
-----END PGP SIGNATURE-----

Obtain the URL for the raw text of the paste. Finally:

<alice> ;;gpg verify http://pastebin.com/XQ0a94Mg
<gribble> Registration successful. You are now authenticated for user 'alice' with key 665FC11DD53E9583

Authentication

The session is for authentication by Alice, assuming she has previously registered her GPG key.

<alice> ;;gpg auth alice
<gribble> Request successful. Your challenge string is: freenode:#bitcoin-otc:cd6e049073b114975c6112d38eb1ecc2cbb3f116b9ac8366d3288d6b

At this point, Alice generates a clearsigned message. The simplest way is to open a shell (or command prompt), and try the following command:

echo freenode:#bitcoin-otc:cd6e049073b114975c6112d38eb1ecc2cbb3f116b9ac8366d3288d6b | gpg --clearsign

Then paste the resulting clearsigned message, including the cleartext header, into a pastebin of your choice. It should look similar to this:

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

freenode:#bitcoin-otc:cd6e049073b114975c6112d38eb1ecc2cbb3f116b9ac8366d3288d6b
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.16 (GNU/Linux)

iEYEARECAAYFAk1z9CQACgkQZl/BHdU+lYOIMwCfTdS0UOJ93KqzaYHF6CqLCr68
buIAoJQcEgQ9EJrPpxGREjN8yRkuKCfD
=XuYu
-----END PGP SIGNATURE-----

Obtain the URL for the raw text of the paste. Finally:

<alice> ;;gpg verify http://pastebin.com/zLEkVNKP
<gribble> You are now authenticated for user 'alice' with key 665FC11DD53E9583

Helper scripts

There's are helper scripts in the git repo that'll simplify the verification step for you. See below for instructions for the specific scripts

Python and Ruby scripts

Download the script (gpgsigner.py or gpgsigner.rb) from the git repo and save it to disk, then you can clearsign and upload your challenge string in one step.

Using python, simply run the script as:

python gpgsigner.py yourchallengestringhere

enter your GPG key passphrase if prompted, and at the end the script will output the pastebin url that you can give to the bot to verify. Same procedure for ruby script.

Perl script

This script pastes the challenge and copies the verification URL automatically, which saves a couple key strokes. To use it, copy the GPG challenge to the clipboard, run this script, paste the clipboard into IRC and you're done.

#!/usr/bin/perl
my $sprunge = 'http://sprunge.us';
my $url = qx{ pbpaste | gpg --clearsign | curl -F 'sprunge=<-' $sprunge };
chomp $url;
system "echo -n ';;gpg verify $url' | pbcopy";

on Linux systems, you can install xclip and use the following aliases

alias pbcopy='xsel --clipboard --input'
alias pbpaste='xsel --clipboard --output'

Colloquy AppleScript

If you are using Colloquy IRC client on OSX, you can use the AppleScript plugin. Download it from the git repo, and put it in ~/Library/Application Support/Colloquy/Plugins. Set the script to +x (executable). Doubleclick on it, and edit in your nickname and passphrase. If you don't want to set your password in the script, you will need to comment out the password line and then uncomment another line near it. Then, in client, just issue ";;gpg auth YOUR_NICKNAME" and the script will do the rest. If by a chance it won't work, just repeat the command.

Irssi script

This script for the Irssi IRC client can automate the registration and the authentication processes. Download the script from the git repo, and put it in the ~/.irssi/scripts/ directory.

To configure the script, you should modify the %nickname_keys array to include your nick and the last 16 hex digits of your key id (or fingerprint). To load the script, run the /script load bitcoin-otc-gpgauth.pl command, or create a symbolic link to the script in the ~/.irssi/scripts/autorun/ directory.

Use the /gpgregister NICKNAME command in the #bitcoin-otc channel to register your nick then the bot will send you a challenge string. Run the /gpgpass PASSPHRASE command to unlock your key and sign the challenge string. To authenticate to the bot, use the /gpgauth NICKNAME command in the same way.

Checking people's authentication status

To check your own authentication status, run gpg ident command without any arguments. To check the status of any nick present on channel, give it one argument - the nick you want to ask about.

To query the database for a registered user, regardless of whether he's authenticated or even present on channel, use the gpg info command. That'll return the registration details on the registered username you query.

Command index

  • Signature-based methods:
    • gpg register - given nick and keyid, initiates registration of your GPG account with the bot.
    • gpg auth - given nick, initiates your authentication to an existing GPG account.
    • gpg verify - given URL of clearsigned message, confirms your identity and authenticates you to the bot.
    • gpg changekey - given new keyid, initiates the process of changing your registered key to the new keyid.
  • Encryption-based methods:
    • gpg eregister - given nick and keyid, initiates registration of your GPG account with the bot.
    • gpg eauth - given nick, initiates your authentication to an existing GPG account.
    • gpg everify - given decrypted one-time password, confirms your identity and authenticates you to the bot.
    • gpg echangekey - given new keyid, initiates the process of changing your registered key to the new keyid.
  • General methods:
    • gpg ident - shows you your own authentication status, or that of an IRC nick you supply.
    • gpg info - shows you the details of registered user account you supply.
    • gpg unauth - terminates your GPG session with the bot.
    • gpg stats - shows summary statistics on the GPG database and user authentications.

Why GPG?

A lot of people ask, why do I need to bother with GPG if I am identified with nickserv and even have a cloak? There are a number of reasons.

  • Freenode opers stop complaining that too many people bother them for cloaks as a result of OTC.
  • Freenode nickserv accounts can be dropped after 60 days of inactivity on the account. This means that any freenode-based account, even a cloaked one, can be taken over.
  • While cloaks are overridden by the web gateway cloak, with GPG auth you can use the systems even through webchat.
  • GPG authentication is exportable - you can prove you own your key in many different contexts. Your WoT account travels with you from IRC, to email, to any other site that supports gpg authentication, or lets you post a gpg-signed message anywhere on your account, like maybe your ebay account page.
  • Authentication is completely independent of network authentication - that means that OTC could easily move from Freenode to any other IRC network, even one without a Nickserv, or cloaking.
  • Finally, the extra geek factor is not to be underestimated, either. :)