Posted by: Eric Hansen
authentication, HOTP, PAM
For some reason, May has seemed to be authentication month for me. I just finished writing an article about SHA-12 encryption for passwords, Two Factor Authentication via SSH, and now I’m here for a new adventure. As mentioned in the two-factor article, I would write about my adventures in using it to authenticate users on the machine itself, not just with SSH. I have perfected this, and I will go into details (and a useful script at the end) for the world to share.
One thing that should be addressed before going into details here is the difference between HOTP and TOTP, as OATH-Toolkit supports both. HOTP stands for HMAC-based One-Time Password. While both HOTP and TOTP (Time-based One-Time Password) are both OTPs, TOTP recycles the valid password after so long (which I will most likely cover in another article as I still haven’t worked out TOTP authentication yet), and HOTP does not. How HOTP works is that when you give that password to the authentication mechanism, the mechanism will see where in the window it exists, and if it’s found, it’ll shift all the records from that point down to the beginning out of the window. It will then not be able to use any of those keys that were shifted, which is implemented to prevent relay attacks from happening.
Also, even though the code is highlighted as PHP, it’s all CLI or Bash text…it’s just that WordPress likes to screw up code usually for me.
Step 1: Installing the Required Software
I was doing testing in a sandbox environment, so I wasn’t using the Google authenticator PAM module, nor have I been happy with it lately. So, I decided to see what else has been released to the Linux community, and stumbled upon (no pun intended) a module that’s been through the wires called OATH-Toolkit. I’m not sure what versions of Linux have this in their package systems, or if it’s up to date, but with Arch Linux it is found in the AUR repository, and is the most up to date version.
One thing to make note of, at least in Arch Linux’s repositories, is that there’s two different versions. There is of course the regular oath-toolkit, but then there’s also oath-toolkit-totp. the TOTP version is just a patched version of the original to include TOTP support (OATH-Toolkit should have this by default, but can’t say for certain). However, according to the official website, OATH-Toolkit supports it natively now, so I’m not sure. Regardless, this will focus on HOTP only.
Anyways, back on track. As I installed via the package manager, I’m not sure of any specific pre-requisites, but it should only depend on PAM, which would have to be installed for most of this to work anyways. However, it should be as simple as:
./configure –prefix=/usr && make check && make install
Step 2: Enable the PAM module
If you’re doing this from the CLI, then make sure you’re logged in as root in a separate window in case something happens. Otherwise, be logged in as root in a separate terminal window. What you’ll need to do is edit the /etc/pam.d/login file. The place of the line depends where in the login process you’ll be asked for the OATH code. Personally for me, I like to be asked after I enter the user password, so mine looks like this (with the non-important parts left out):
auth required pam_securetty.so
auth requisite pam_nologin.so
auth required pam_unix.so nullok
auth required pam_oath.so usersfile=/etc/oath-auth/login window=276447231 digits=6
If you want the OATH password to be required prior to the account password, just put the last line before auth require pam_unix.so nullok
The line of importance (and that you have to add) is the auth required pam_oath.so… The extra features I passed to it is to tell the module where to find the users file (which I’ll go into detail next), and the window size (how many records to search for). TOTP has been reported (via the mailing list) to force the window to be 0, and I’m not sure what happens if the window is 0, but I do know that 276447231 is the max value. If you want to test this, add the option “debug” and change the window size to 99999999999999 (14 9′s). Just make sure you take out the “debug” option before deployment.
Step 3: Create the usersfile
Make note of what you set it to in the PAM module option. This is the file we will be creating now. When you have your favorite editor opened for the file, enter the following line:
HOTP user – key
For example, to make it an easy root authentication, it’d be
HOTP root – 00
Breaking it down, HOTP tells OATH-Toolkit what type of authentication it is. After that will be the username to authenticate, followed by a password the user has to give (this is for two-factor authentication which I will write about when I’m more clear on how it works), then the key to generate the window with. Now, while it is safer to disable root from being able to log in, for this example we’ll assume it’s possible.
After that, save the file and then do the following to the file:
chmod 600 usersfile
Now that we’re almost there, it’s time to make sure it all works. But, first, we need to generate some keys to work with.
Step 4: Creating Testing Keys
Please note that these keys will not change values (that’s what TOTP does). What you need to do is remember the key you gave the user (for example, above, root was given the key 00). Once you have that ready, we will use oathtool to generate keys to use. For this, we will simply do:
oathtool -w 10 00
Remember to replace 00 with the key you gave the account, though. This will generate 10 keys (-w means window size, and -w 10 means create a 10-key window of possibilities). You can try any of the keys given, but remember that when you use one, any of the ones found below will no longer work for that user.
Step 5: Test the log-in
Now it’s the moment of truth. Assuming you’re in a CLI environment (which makes this so much easier), open up a new TTY session (by default, it’s Alt+F[1...12]). Then, try to log in with any user account you set up in the usersfile. If everything goes according to plan, you’ll be logged in. However, if any problems occurred, hopefully you still have an active root session available where you can edit /etc/pam.d/login and add the “debug” option to the pam_oath.o module line. If you have any issues, feel free to leave a comment and I’ll do my best to help you, as I know finding assistance with this module is not the easiest.
Step 6 (optional): Generating usersfile Accounts
After making sure authentication works, you’ll probably want to add more users. For this, a bash script makes life so much easier. That is what I’m going to supply you now (which is probably a little over-done, but I felt like being overly creative):
if [ -n "$1" ]; then
echo “Username must be specified.”
if [ -n "$2" ]; then
if [ -d /etc/oath-auth/login ]; then
echo -n “Please enter the path to the login file: ”
KEY=$(cat /dev/urandom | tr -cd ‘a-f0-9′ | head -c 32)
RECORD=$(echo -n “HOTP $USER $PASS $KEY”)
echo -e “The following record will be appended into $OATH_AUTH_FILE:\n$RECORD\n$
if [ "$CHOICE" == "n" ] ; then
echo “Nothing was done.”
echo “$RECORD” >> $OATH_AUTH_FILE
echo -e “\n\nOutput of $OATH_AUTH_FILE now:\n”
Basically this generates a 32-character hex string to use with your OATH authenticator. You can always edit this to suite your needs, and some of this is pointless to have in the script (like providing the script path), but it can also be useful if you decide to use this for more than just logging in (for example, use this for SSH instead of the Google module).
This was a fun project to work on, and glad I gained the experience and knowledge. I set this up on my laptop for no real reason, but since they are usually targets of theft and such, it’ll be near useless to try to log into the system now hehe. I’ll write more about OATH-Toolkit later as I do quite enjoy this module and would love to really learn how to implement TOTP as well, and two-factor authentication…even though two-factor is already done now using both the pam_unix.so and pam_oath.so modules.