{"id":761,"date":"2015-12-08T08:25:03","date_gmt":"2015-12-08T08:25:03","guid":{"rendered":"http:\/\/adriangrigoras.com\/blog\/?p=761"},"modified":"2016-12-08T08:25:42","modified_gmt":"2016-12-08T08:25:42","slug":"perl-google-authenticator","status":"publish","type":"post","link":"https:\/\/adriangrigoras.com\/blog\/perl-google-authenticator\/","title":{"rendered":"Perl and Google Authenticator"},"content":{"rendered":"

In this article I’ll explain (with code) how to create<\/em> and validate<\/em> a Google Authenticator two-step authentication token, using Perl. Both on the command-line and on a simple website.<\/p>\n

Some background<\/h1>\n

Google Authenticator is a two-step authentication process created by Google. It’s software based, unlike those hardware tokens your bank may use, and when paired with a service it provides a six digit number which must be used alongside one’s credentials to log in to a service which requires use of it.<\/p>\n

Google provides software versions of the Authenticator for iOS, Blackberry, Android, and a number of other platforms, including “native” Windows executables, or even HTML5 web applications.<\/p>\n

Google generates an 80-bit secret key for each user, saves it, and then displays it (encoded in base32) to the user in the form of a QR code. The user can then use their mobile application to input it, and use the generated six-digits to authenticate from then onwards.<\/p>\n

The application “simply” creates a HMAC-SHA1 using the secret key, using the “number of 30-seconds periods elapsed since the Epoch” as the message. A part of this is extracted and converted to the six-digit code.<\/p>\n

\u00a0How do I create a Google Authenticator secret?<\/h1>\n

At its most basic, the “secret” comprises of 10 bytes from \/dev\/urandom. That’s it. For more security, one would want to get more than just 10 bytes. Say, 50:<\/p>\n

my $len_secret_bytes = 50;\r\nopen my $RNG, '<', '\/dev\/urandom'\r\n  or die \"Cannot open \/dev\/urandom for reading: $!\";\r\nsysread $RNG, my $secret_bytes, $len_secret_bytes\r\n  or die \"Cannot read $len_secret_bytes from \/dev\/urandom: $!\";\r\nclose $RNG\r\n  or die \"Cannot close \/dev\/urandom: $!\";<\/pre>\n
Since you will want to have users input the secret data in the Authenticator application, or have them snap a picture of the QR code to input it in the application, you’ll have to convert those $secret_bytes<\/tt> to Base32:<\/p>\n
use Convert::Base32;\r\nmy $secret_base32 = encode_base32( $secret_bytes );<\/pre>\n
You will want to save that $secret_base32<\/tt> somewhere like in a database (next to the “password_bcrypt” for the user), or in a flat file (in ~\/.google_authenticator) that is user-specific, since you and your users will want to have it handy: without it, you won’t be able to verify their six-digit code, and they won’t be able to either.<\/p>\n
\u00a0Displaying the QR code<\/h2>\n
Now you have the $secret_base32<\/tt>. You can just display that to the users, and they’ll be able to manually enter it on the Google Authenticator app.<\/p>\n
Or, you can have that displayed as a nice QR code they can simply take a picture of, and the app will add the account for them. To do that, you will just need two things: the $secret_base32<\/tt> code you have already generated for the user, and a $label<\/tt> you want your users to associate with that secret, for example foo@example.com on Your Website<\/tt>.<\/p>\n
use URI::Escape;\r\nmy $url   = sprintf(\"otpauth:\/\/totp\/%s?secret=%s\", $label, $secret_base32);\r\nmy $qr_url = sprintf(\"https:\/\/www.google.com\/chart?chs=200x200\" .\r\n    \"&chld=M|0&cht=qr&chl=%s\", uri_escape($url));<\/pre>\n
You can then embed that QR code URL inside an <img><\/tt> tag and your users will be able to easily add the Google Authenticator secret you have generated for them to their app.<\/p>\n
\u00a0How to authenticate users<\/h1>\n
You have generated a Google Authenticator code for a user, they have added it to their app via a QR code, and now they’d like to… use it!<\/p>\n
Once you have a user’s $secret_base32<\/tt> you can check whether the $given_token<\/tt> they give you is the correct one, in which case you can continue on checking their password, or not:<\/p>\n
use Authen::OATH;\r\nuse Convert::Base32;\r\nmy $correct_token = make_token_6(\r\n    Authen::OATH->new->totp(\r\n        decode_base32( $secret_base32 )\r\n    )\r\n);\r\n$given_token = make_token_6($given_token);\r\n\r\nif ($given_token eq $correct_token) {\r\n    print \"Yup!\"\r\n    #\u00a0Check password, etc.\r\n} else {\r\n    print \"Nope!\"\r\n}\r\n\r\nsub make_token_6 {\r\n    my $token = shift;\r\n    while (length $token < 6) {\r\n        $token = \"0$token\";\r\n    }\r\n    return $token;\r\n}<\/pre>\n
The above method will only authenticate users against the current<\/em> value shown on their Google Authenticator. If their device’s clock (or your server’s clock) drifts too much, they may have problems authenticating against your server.<\/p>\n
If you’re comfortable enough with a 30-seconds drifting either way, you can look into the following optional parameter for ->totp<\/tt>:<\/p>\n
my $otp = $oath->totp( $secret [, $manual_time ] );<\/pre>\n
You will then be able to compute:<\/p>\n
my @possible_tokens =\r\n    map { $oath->totp($secret, $_) }\r\n        time-30, time, time+30;<\/pre>\n
And check either of @possible_tokens<\/tt> against the $given_token<\/tt>.<\/p>\n
\u00a0Conclusions<\/h1>\n
If you have read through this article, you should now be able to use Perl and the CPAN to:<\/p>\n