From ArchWiki
Jump to navigation Jump to search

The OATH Toolkit provides a two-step authentication procedure using one-time passcodes (OTP). It complies to two OTP method RFC standards (HOTP, TOTP). The OTP generator applications are available for iOS, Android, Blackberry and other devices. Similar to Google Authenticator the authentication mechanism integrates into the Linux PAM system. This guide shows the installation and configuration of this mechanism.


Install the oath-toolkit package.

Setting up the oath

The oath seed is an hexadecimal number that should be unique per user. To generate a new seed for a user, you could use the following command line:

$ head -10 /dev/urandom | sha512sum | cut -b 1-30

Note the above output seed is used as example seed in this article and must not be used. There needs to be one oath per user and link to it in a configuration file /etc/users.oath. While being root create the file and insert the user seed:

# Option User Prefix Seed
HOTP/T30/6 user - 1ab4321412aebcw

Make sure that the file can only be accessed by root:

 # chmod 600 /etc/users.oath
 # chown root /etc/users.oath

Setting up the PAM

To enable oath for a specific service only, like ssh, you can edit the file /etc/pam.d/sshd and add at the beginning of the file the following line:

 auth	  sufficient usersfile=/etc/users.oath window=30 digits=6

This will allow authentication if you just enter the right oath code. You can make it a requirement and let the rest of the pam stack be processed if you use the following line instead:

 auth	  required usersfile=/etc/users.oath window=30 digits=6

For ssh login to work make sure that both ChallengeResponseAuthentication and UsePAM options are enabled:

 ChallengeResponseAuthentication yes
 UsePAM yes

If you want to force OATH request-response even if there is a working public/private key authentication also add the following:

 AuthenticationMethods publickey,keyboard-interactive
 PasswordAuthentication yes

Logging with an oath pass

Run the following command if you are logging in and need the current oath pass :

 oathtool -v -d6 1ab4321412aebcw

Of course replace 1ab4321412aebcw by the seed corresponding to your user. It will display something like that :

 Hex secret: 1ab4321412aebc
 Base32 secret: DK2DEFASV26A====
 Digits: 6
 Window size: 0
 Start counter: 0x0 (0)

The last number is actually the code you can use to log in right now, but more interestingly the Base32 secret, is actually what we need to generate a qr code for this user. To do so install the package qrencode to run the following command :

 qrencode -o user.png 'otpauth://totp/user@machine?secret=DK2DEFASV26A===='

Of course change user, machine and DK2DEFASV26A==== accordingly. Once done, you can visualize your qrcode with your preferred image visualizer application and use that to configure your phone. It is pretty straight forward to use FreeOTP to then take a screenshot of that .png and get it to display OTP pass when needed.

Note: The secret key of your users is the most important information in this system. Once you setup a phone to provide OTP, it does have that key. The qr code in that .png file does have that key. You need to take extra care of this file. They should only be stored on encrypted medium (Your phone need to be using encryption for any sane level of security). If not even confined in a sandbox like Samsung Knox to prevent third party application to potentially access them.

See also