Project:Infrastructure/dev.gentoo.org 2-step authentication

The SSH server on our developer machine (dev.gentoo.org) now has an experimental support for 2-step authentication, in which the usual public key authentication is followed by HOTP/TOTP input (see also: article on Two-factor authentication). The two-step authentication is implemented using PAM module.

TOTP with default settings
In order to enable two-step authentication with the default settings, you can use our simple wrapper script:

The above summary includes a QRCode for easy setup (you may need to zoom the terminal out to use it) and the Base32-encoded secret for manual setup. It also includes a verification code which will probably expire before you manage to set it up, and 5 emergency scratch codes that you should write down and keep in a safe place.

After enabling it, please make sure to test it using a parallel session. If you lock yourself out, you can use the emergency codes to login.

The default settings are:
 * TOTP (as specified in RFC6238) with SHA-1 algorithm and X=30 second period
 * window of 3 codes allowed (i.e. the previous one, the current one and the next one), accounting for a clock drift of ±30 seconds
 * code reuse disallowed (i.e. you can't use the same TOTP code to establish two sessions, you need to wait for the next one)
 * rate limiting to 3 attempts over 30 seconds
 * 5 emergency scratch codes

HOTP or TOTP with custom settings
If you'd like to use different settings, you can run the configuration app directly and follow the on-screen instructions:

There are also some additional options available only via command-line arguments.

Disabling HOTP/TOTP
In order to disable the two-step authentication, just remove the configuration file: