#31: Support multiple devices per user

AUTHORS

@@ -9,6 +9,7 @@ Francisco Javier Tsao Santín <[email protected]>
 Gabriel Owczarski <gabriel@asus.(none)>
 Georg Hopp <[email protected]>
 IGP <[email protected]>
+João Figueiredo <[email protected]>
 Luka Novsak <[email protected]>
 McDope <[email protected]>
 Omar Mostafa <[email protected]>

ChangeLog

@@ -1,3 +1,21 @@
+* 0.8.3
+  [Enhancement] Install pam-auth-update config only on systems having it
+  [Feature] pamusb-conf now has a --reset-pads=username option
+  [Bugfix] Fix RHOST check triggering on empty value
+  [Packaging] Add make targets for Fedora/RPM builds
+  [Packaging] Add make targets for source distribution
+  [Packaging] Add make targets for Arch/ZST builds
+  [Packaging] Improve PKGBUILD for Arch (thx @IslandC0der)
+  [Packaging] Fix debian autoconfig picking up serials as devices if they have no revision set
+  [Makefile] make install no longer overwrites the config if it already exists
+  [Makefile] Add target to update doc/ textfiles from wiki
+  [Bugfix] Whitelist pamusb-agent for remoteness-check
+  [Bugfix] Fix "tty from displayserver" remoteness-check method
+  [CI/Tests] Many additions, fixes and automatic nighly builds
+  [CI/Tests] Add testcase ensuring pamusb-agent properly triggers
+  [Docs] Update manpages and text files
+  [Bugfix] Fix some usages of tmux being able to circumvent localcheck
+
 * 0.8.2
   [Tools/Docs] Add pamusb-keyring-unlock-gnome, to allow unlocking the GNOME keyring (#11)
   [Bugfix] Whitelist "login" service name to prevent insta-logout on TTY shells (#115)

README.md

@@ -4,16 +4,16 @@
 pam\_usb
 ========
 
-pam\_usb provides hardware authentication for Linux using ordinary USB Flash Drives.
+pam\_usb provides hardware authentication for Linux using ordinary removable media. Tested are flash sticks and storage cards, but it should work with harddrives, SSDs and even floppies (at least USB based) too.
 
 It works with any application supporting PAM, such as _su_ and login managers (_GDM_, _KDM_).
 
 Features
 --------
 
-* `Password-less authentication.` Use your USB stick for authentication, don't type passwords anymore.
+* `Password-less authentication.` Use your removable media for authentication, don't type passwords anymore (or add a second factor).
 * `Device auto probing.` You don't need to mount the device, or even to configure the device location (_sda1_, _sdb1_, etc). pam\_usb.so will automatically locate the device using `UDisks` and access its data by itself.
-* `Two-factor authentication.` Achieve greater security by requiring both the USB stick and the password to authenticate the user.
+* `Two-factor authentication.` Archive greater security by requiring both the removable media and the password to authenticate the user.
 * `Non-intrusive.` pam\_usb doesn't require any modifications of the USB storage device to work (no additional partitions required).
 * USB Serial number, model and vendor verification.
 * Support for **One Time Pads** authentication.
@@ -53,5 +53,5 @@ This repo is mainly based on community improvements from
 See the commit history for details. You can find a list of all contributors in the `AUTHORS` file. 
 
 The last official release was 0.5.0 btw, some private packages used 0.6.0 to override the upstream provided 
-version but those varied in changes from 0.5.0. This repo will be released starting from 0.7.0 when ready
-and includes all updates I'm aware of (Python3 port, UDisks2 support, other smaller ones) or did myself.
+version but those varied in changes from 0.5.0. This repo started at 0.7.0 and includes all contributions up
+to this point I'm aware of (Python3 port, UDisks2 support, other smaller ones) or did myself.

arch_linux/PKGBUILD_stable

@@ -2,7 +2,7 @@
 # Contributor: Pekka Helenius <fincer89 [at] hotmail [dot] com>
 
 pkgname=pam_usb
-pkgver=0.8.2
+pkgver=0.8.3
 pkgrel=4
 pkgdesc='Hardware authentication for Linux using ordinary flash media (USB & Card based).'
 arch=($CARCH)

debian/changelog

@@ -1,3 +1,14 @@
+libpam-usb (0.8.3) unstable; urgency=medium
+  * [Feature] pamusb-conf now has a --reset-pads=username option
+  * [Bugfix] Fix debconf issues with devices having no revision set
+  * [Bugfix] Fix RHOST check triggering on empty value
+  * [Bugfix] Whitelist pamusb-agent for remoteness-check
+  * [Bugfix] Fix "tty from displayserver" remoteness-check method
+  * [Docs] Update manpages and text files
+  * [Bugfix] Fix some usages of tmux being able to circumvent localcheck
+
+ -- Tobias Bäumer <[email protected]>  Wed, 24 Aug 2022 21:00:00 +0200
+
 libpam-usb (0.8.2) unstable; urgency=medium
   * [Tools/Docs] Add pamusb-keyring-unlock-gnome, to allow unlocking the
   GNOME keyring (#11)

debian/config

@@ -9,7 +9,7 @@ then
     CHOICES=""
 
     # Iterate over each drive (note that we are reversing the list because udisksctl order is inverted from pamusb-conf/python api)
-    for DRIVE in `udisksctl status | grep -o '  \S[a-z]\S*' | tr -d ' ' | tac`
+    for DRIVE in `udisksctl status | grep -o '  \S[a-z]\S* $' | tr -d ' ' | tac`
     do
         # echo "Debug: Handling drive /dev/$DRIVE.."
 

debian/source/options

@@ -1,4 +1,6 @@
 tar-ignore = .idea
 tar-ignore = .vscode
 tar-ignore = arch_linux
-tar-ignore = .github
+tar-ignore = fedora
+tar-ignore = .github
+tar-ignore = .build

doc/CONFIGURATION

@@ -104,6 +104,8 @@ The syntax is the following:
 Some cheap devices don't report a vendor and/or model. To use these devices you can use "Generic" for these values, then it won't be checked.
 Be aware that this reduces security if you have `one_time_pads` disabled since the device containing the volume won't be checked anymore (but these attributes could be faked with a custom firmware anyway).
 
+You can configure as many devices as you want, but each user can only be configured to use a single device (currently).
+
 ### Example:
 
 ```xml
@@ -122,7 +124,7 @@ Be aware that this reduces security if you have `one_time_pads` disabled since t
 |   Name   |   Type    |                Description                |  Example   |
 |----------|-----------|-------------------------------------------|------------|
 | `id`     | Attribute | Login of the user                         | `root`     |
-| `device` | Attribute | `id` of the device associated to the user | `MyDevice` |
+| `device` | Element   | `id` of the device associated to the user | `MyDevice` |
 | `agent`  | Element   | Agent commands, for use with pamusb-agent |            |
 
 ### Agent
@@ -212,40 +214,34 @@ pamusb-agent -c /some/other/path.conf
 Example configuration
 ----------------------------------
 
-**NOTE**: For detailed information, rely on repository wiki pages.
+1. Insert a removable block device
 
-* **1)** Insert an USB block device
-* **2)** Add necessary user configuration into `/etc/security/pam_usb.conf` by running:
+2. Add necessary device configuration into `/etc/security/pam_usb.conf` by running:
 
 ```
-sudo pamusb-conf --add-user=<username>
+sudo pamusb-conf --add-device=<devicename>
 ```
 
-where `<username>` is a valid Unix user name.
+where `<devicename>` is a recognizable name for your device. This value is used internally in the configuration file as device `id` value and in output shown to users. (Note: because of it being used as an XML attribute value, it shouldn't contain ampersands etc.)
 
-* **3)** Add necessary device configuration into `/etc/security/pam_usb.conf` by running:
+3. Add necessary user configuration into `/etc/security/pam_usb.conf` by running:
 
 ```
-sudo pamusb-conf --add-device=<devicename>
+sudo pamusb-conf --add-user=<username>
 ```
 
-where `<devicename>` is a recognizable name for your device. This value is only used internally in the configuration file as device `id` value.
-
-* **4)** Tweak `/etc/security/pam_usb.conf` manually as desired. Link devices and users, etc.
-
-**NOTE**: If you don't want to use one time pad files, consider setting `one_time_pad` option to `false`. Pad file use defaults to `true`.
+where `<username>` is a valid Unix user name.
 
-If you use one time pads, you need to do the following:
+4. Tweak `/etc/security/pam_usb.conf` manually as desired. Link devices and users, etc.
 
-* **5)** Manually mount USB block device partition. You need write access to the mounted partition.
+If you use one time pads (default), you need to do the following:
 
-* **6)** Run `/usr/bin/pamusb-check --debug --service=pamusb-agent <username>`
+5. Run `/usr/bin/pamusb-check --debug <username>`
 
-where `<username>` is associated with the USB block device.
+where `<username>` is associated with the removable block device.
 
 By default, this command creates directory `$HOME/.pamusb/` with a protected device-associated `.pad` file. If you format the device, you must
-delete `$HOME/.pamusb/<devicename>.pad` file. The created `.pad` file can't be used with a new partition UUIDs for the same or any USB block device.
+delete the `$HOME/.pamusb/<devicename>.pad` file (or run `pamusb-conf --reset-pads=username`). The created `.pad` file can't be used with a new partition UUIDs for the same or any removable block device.
 
-* **7)** Unmount the USB block device.
-* **8)** Add proper PAM configuration into `/etc/pam.d/common-auth` as described in [Getting Started](https://github.com/mcdope/pam_usb/wiki/Getting-Started#setting-up-the-pam-module). For testing purposes, it's highly recommended to start with `sufficient` PAM option before possibly moving to `required` or `requisite` option since you can bypass faulty `pam_usb` configurations.
-* **9)** Test the device/user configuration by running `sudo echo "pam_usb test"`. The USB block device must be attached (mount not required) and the user must have proper configuration in `/etc/security/pam_usb.conf` file.
+6. Add proper PAM configuration into `/etc/pam.d/common-auth` as described in [Getting Started](https://github.com/mcdope/pam_usb/wiki/Getting-Started#setting-up-the-pam-module). For testing purposes, it's highly recommended to start with `sufficient` PAM option before possibly moving to `required` or `requisite` option since you can bypass faulty `pam_usb` configurations.
+7. Test the device/user configuration by running `/usr/bin/pamusb-check <username>`. The removable block device must be attached (mount not required) and the user must have proper configuration in `/etc/security/pam_usb.conf` file.

doc/QUICKSTART

@@ -28,7 +28,9 @@ Once you've connected your USB device to the computer, use pamusb-conf to add it
     [Y/n] y
     Done.
 
-Note that `MyDevice` can be any arbitrary name you'd like. Also, you can add as many devices as you want.
+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, each user can currently only use a single device so additional devices can only be used for additional users.
 
 Next, configure users you want to be able to authenticate with pam_usb:
 
@@ -73,20 +75,22 @@ Your default PAM common-auth configuration should include the following line:
 
 This is a current standard which uses passwords to authenticate a user.
 
-Alter your /etc/pam.d/common-auth configuration to:
+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 USB device plugged-in.
+At this point, you should be able to authenticate with the relevant removable device plugged-in.
 
     scox $ su
     * pam_usb v.SVN
@@ -103,7 +107,7 @@ 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.
+(`/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.
@@ -113,7 +117,9 @@ You can find details in [the "Agent" section of Configuration](https://github.co
 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. 
+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

doc/TROUBLESHOOTING

@@ -65,4 +65,11 @@ It can happen if you remove the authentication device without unmounting it befo
 
 Or, worst case scenario - someone tried to tamper with your system. In example someone could deep-clone (not only FS but also HW Ids) your authentication device and use it to login or sudo (if you use pamusb as the only factor), pads will then be updated on system and the attacking device but not on your original device since it wasn't connected at the time of your login. On next authentication request with your original device you will then get "Pad checking failed!". Of course for most persons this is an unlikely scenario. But if your system and/or device is accessible to other persons, keep it in mind. 
 
-To fix this you can just remove the `<DEVICENAME>.pad` file for your device in `~/.pamusb`. The pad will then be regenerated on next authentication request. If that doesn't make the error go away, it will be the device pad causing it, which you can find at `<authdevice-mount>/.pamusb`. Since version 0.8.3 you can also use `pamusb-conf --reset-pads=<USERNAME>`
+To resolve this you can use `pamusb-conf --reset-pads=<USERNAME>`, which will remove the pad files for the given user and its configured device so they will be regenerated on next authentication.
+
+Agent configuration / commands don't work like expected
+--------------
+
+The agent will log all executed commands, as well as their exitcode; stdout and stderr (since v0.8.3). You can view this log either via systemd, or - easier - by `tail`'ing `/var/log/auth.log`.
+
+You can use this to a) verify your config is picked up like expected and b) configured commands do what you want. For some programs, esp. ones expecting to be run within a graphical environment, you will have to provide environment values via `<env>` tags in the agent configuration. Usually the log will provide you with some good clues. But feel free to open a support issue if you need help.

doc/pam_usb.conf

@@ -22,6 +22,13 @@ See http://www.pamusb.org/doc/configuring
 						<volume_uuid>6F6B-42FC</volume_uuid>
 						<option name="probe_timeout">10</option>
 				</device>
+				<device id="MySecondDevice">
+						<vendor>Commodore</vendor>
+						<model>REU</model>
+						<serial>CMDKXXXXXXXXXXXXXXXX</serial>
+						<volume_uuid>6F6B-00FF</volume_uuid>
+						<option name="probe_timeout">10</option>
+				</device>
 				-->
 		</devices>
 
@@ -38,6 +45,7 @@ See http://www.pamusb.org/doc/configuring
 						removal:
 						<user id="scox">
 								<device>MyDevice</device>
+								<device>MySecondDevice</device>
 								<option name="quiet">true</option>
 								<agent event="lock">
 									<cmd>gnome-screensaver-command -\-lock</cmd>

fedora/SPECS/pam_usb.spec

@@ -1,7 +1,7 @@
 %define _topdir         /usr/local/src/pam_usb/fedora
 %define name            pam_usb 
 %define release         1
-%define version         0.8.2
+%define version         0.8.3
 %define buildroot       %{_topdir}/%{name}‑%{version}‑root
 
 BuildRoot: %{buildroot}
@@ -56,7 +56,16 @@ rm -rf %{buildroot}/usr/share/pam-configs
 %doc %attr(0644,root,root) /usr/share/doc/pam_usb/TROUBLESHOOTING
 
 %changelog
-* Sun May 22 2022 McDope <[email protected]> - 0.8.2-1
+* Wed Aug 24 2022 Tobias Bäumer <[email protected]> - 0.8.3-1
+- [Enhancement] Install pam-auth-update config only on systems having it
+- [Feature] pamusb-conf now has a --reset-pads=username option
+- [Bugfix] Fix RHOST check triggering on empty value
+- [Bugfix] Whitelist pamusb-agent for remoteness-check
+- [Bugfix] Fix "tty from displayserver" remoteness-check method
+- [Docs] Update manpages and text files
+- [Bugfix] Fix some usages of tmux being able to circumvent localcheck
+
+* Sun May 22 2022 Tobias Bäumer <[email protected]> - 0.8.2-1
 - First version being packaged for RPM
 - [Tools/Docs] Add pamusb-keyring-unlock-gnome, to allow unlocking the GNOME keyring (#11)
 - [Bugfix] Whitelist "login" service name to prevent insta-logout on TTY shells (#115)