Getting Started

Quickstart

Note: If you installed by using the debian package and answered the configuration questions you already have a working setup. If you skipped the questions you will still already have the PAM module itself already setup. Continue with "Setting up Devices and Users" in that case.

Setting up pam_usb requires the following, once pam_usb is installed:

1. Set up devices and users
2. Configuring PAM for system authentication
3. (Optional) Configuring pamusb-agent to run programs when the device is inserted or removed

Setting up Devices and Users

Once you've connected your USB device to the computer, use pamusb-conf to add it to the configuration file:

# pamusb-conf --add-device MyDevice
Please select the device you wish to add.
* Using "SanDisk Corp. Cruzer Titanium (SNDKXXXXXXXXXXXXXXXX)" (only option)
Which volume would you like to use for storing data ?
* Using "/dev/sda1 (UUID: <6F6B-42FC>)" (only option)
Name            : MyDevice
Vendor          : SanDisk Corp.
Model           : Cruzer Titanium
Serial          : SNDKXXXXXXXXXXXXXXXX
Volume UUID     : 6F6B-42FC (/dev/sda1)
Save to /etc/security/pam_usb.conf ?
[Y/n] y
Done.

Note that MyDevice can be any arbitrary name you'd like, but will be used as an XML attribute value so stay away from any special characters and stick to A-Z.

Also, you can add as many devices as you want. However, in versions prior to v0.8.5 each user can currently only use a single device so additional devices can only be used for additional users. Starting from v0.8.5 a single user can have multiple devices assigned as well.

Next, configure users you want to be able to authenticate with pam_usb:

# pamusb-conf --add-user username
Which device would you like to use for authentication ?
* Using "MyDevice" (only option)
User            : username
Device          : MyDevice
Save to /etc/security/pam_usb.conf ?
[Y/n] y
Done.

Check the configuration

You can run pamusb-check anytime to check if everything is correctly worked. This tool will simulate an authentication request (requires your device to be connected, otherwise it will fail).

# pamusb-check username
* Authentication request for user "username" (pamusb-check)
* Device "MyDevice" is connected (good).
* Performing one time pad verification...
* Verification match, updating one time pads...
* Access granted.

Setting up the PAM module

Before you do this step you should read into how pam.d configuration works. If you make the wrong changes you could easily end up with a system where you can't login at all - requiring you to use recovery mode to revert your changes.

See https://manpages.ubuntu.com/manpages/impish/en/man7/PAM.7.html for a quick explanation of PAM and https://manpages.ubuntu.com/manpages/impish/man5/pam.d.5.html for a configuration file guide. If you aren't on a Debian based distro check your system man pages for them since there will be some differences most likely.

To add pam_usb into the system authentication process, we need to edit /etc/pam.d/common-auth

NOTE: If you are using RedHat, Arch or Fedora this file can be known as `/etc/pam.d/system-auth`.  
Some distributions also require you to additionally insert the line into `/etc/pam.d/password-auth`.

Your default PAM common-auth configuration should include the following line:

auth    required        pam_unix.so nullok_secure

This is a current standard which uses passwords to authenticate a user.

Alter your /etc/pam.d/common-auth configuration to:

auth    sufficient      pam_usb.so
auth    required        pam_unix.so nullok_secure

Remember what we've learned in the pam manpages (you've read them, riiiight?): pam rules are a stack, order of the rules is important and makes a difference in behavior.

Use pam_usb to replace your password

The sufficient keyword means that if pam_usb allows the authentication, then no password will be asked. If the authentication fails, then the default password-based authentication will be used as fallback.

Use pam_usb as 2nd factor in addition to your password

If you change it to required, it means that both the USB flash drive and the password will be required to grant access to the system.

At this point, you should be able to authenticate with the relevant removable device plugged-in.

scox $ sudo bash
* Authentication request for user "scox" (sudo)
* Authentication device "MyDevice" is connected.
* Performing one time pad verification...
* Regenerating new pads...
* Access granted.

Agent

The pam_usb agent (pamusb-agent) allows you to automatically execute commands upon locking and unlocking events. Those events are generated when you insert or remove your authentication device. To configure the commands, you have to edit pam_usb's configuration file (/etc/security/pam_usb.conf) and add agent entries into your user section.

For instance, you could automatically start your screensaver as soon as you remove the device, and deactivate it when you plug the device back.

You can find details in the "Agent" section of Configuration

Auto-unlock your GNOME keyring

You should think twice if you want to enable this feature. To use it you need to put your keyring password in cleartext into your home directory.

The tool will only work if that file has permissions only for the owner, however - anyone with root/sudo access will still be able to read it. Keep that in mind before using this feature. Even worse: if you have samba user shares enabled you would share your password via SMB shares - to whoever can access that share. To be clear: this is a comfort feature and is insecure by design.

If you still want to use it, you will have to do four things:

• create .keyring_unlock_password in your home directory
• in that file you put UNLOCK_PASSWORD="your_password" (including the quotes)
• set permissions so only yourself (and root) can read the file by running chmod 0600 ~/.keyring_unlock_password
• create an autostart entry in GNOME for /usr/bin/pamusb-keyring-unlock-gnome

Fine Tuning

There are many options available to configure pam_usb.

Check out the configuration reference.