pam_oath - ArchWiki

Jump to content

Related articles

- OATH
- Google Authenticator
- YubiKey

The OATH Toolkit provides one-time password (OTP) components for authentication systems. It contains a PAM authentication module that supports HOTP and TOTP as described by their informational RFC, RFC 4226 and RFC 6328 respectively. 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.

## Installation

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:

    $ openssl rand -hex 10

    12345678909876543210

Note: The above output seed is used as example 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:

Warning: Do not use T bigger than 60. You will get (OATH_UNKNOWN_USER: Cannot find information about user).

    /etc/users.oath

    # Option User Prefix Seed
    HOTP/T30/6 user - 12345678909876543210

If you want only event based OTP, create this file:

    /etc/users.oath

    # Option User Prefix Seed
    HOTP user - 12345678909876543210

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 pam_oath.so 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 pam_oath.so usersfile=/etc/users.oath window=30 digits=6

For ssh login to work, make sure these options are enabled in the file `/etc/ssh/sshd_config`:

    ChallengeResponseAuthentication yes
    UsePAM yes

Restart `sshd.service` to enable the changes.

If you want to force OATH request-response even if there is a working public key authentication and password authentication also add the following in `/etc/ssh/sshd_config`:

    AuthenticationMethods publickey,keyboard-interactive:pam
    KbdInteractiveAuthentication yes
    PasswordAuthentication yes

Tip: For desktop console login, just edit `/etc/pam.d/login`.

## Logging with an oath pass

Use oathtool for getting the one time password and further information.

To get some information about the tool, run

    $ oathtool --help

For logging in with TOTP (HOTP/T30/6... in users.oath):

    $ oathtool -v --totp -d 6 12345678909876543210

Warning: There is a bug when TOTP mode setting "SHA512", but the developers did not fix it. See the open issue on Gitlab.
Note: Setting the TOTP mode to "SHA256" or "SHA512" and increasing the number of one-time passwords may not be necessary as attackers can brute force your keys, increasing the length of the keys and limit the number of login attempts will mitigate the attack. See Delay after failed login and Lock out after failed login.

If you are logging in with HOTP (HOTP... in users.oath):

    $ oathtool -v -d 6 12345678909876543210

Of course replace `12345678909876543210` 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)

    820170

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 QR code with your preferred image visualizer application and use that to configure your phone. Alternatively you may generate the QR code directly onto terminal with:

    $ qrencode -t UTF8 'otpauth://totp/user@machine?secret=DK2DEFASV26A===='

It is pretty straight forward to use FreeOTP+ to then take a screenshot of that .png (or ASCII-art like image) 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

- Two-factor time based (TOTP) SSH authentication with pam_oath and Google Authenticator
- pam_oath manual

Categories:

- Secure Shell
- Authentication