Skip to content

Configuration

Jump to bottom
McDope edited this page Aug 1, 2024 · 13 revisions

Configuration file reference

The configuration file is formatted in XML and subdivided in 4 sections:

  • Default options, shared among every device, user and service
  • Devices declaration and settings
  • Users declaration and settings
  • Services declaration and settings

Note that for changes to the agent / events config you need to restart the agent service for them to take effect. Other changes are picked up on next pam_usb usage.

The syntax is the following:

<configuration>
    <defaults>
        <!-- default options -->
    </defaults>

    <devices>
        <!-- devices definitions -->
    </devices>

    <users>
        <!-- users definitions -->
    </users>

    <services>
        <!-- services definitions -->
    </services>
</configuration>

Options

Name Type Default Description
enable Boolean true Enable pam_usb
debug Boolean false Enable debug messages
quiet Boolean false Quiet mode
color_log Boolean true Enable colored output
one_time_pad Boolean true Enable the use of one time device-associated pad files
deny_remote Boolean true Deny access from remote host (SSH)
probe_timeout Time 10s Time to wait for the volume to be detected
pad_expiration Time 1h Time between pad file regeneration
hostname String Computer's hostname Must be unique accross computers using the same device
system_pad_directory String .pamusb Relative path to the user's home used to store one time pads
device_pad_directory String .pamusb Relative path to the device used to store one time pad files

Example:

<configuration>
    <defaults>
        <!-- Disable colored output by default -->
        <option name="color_log">false</option>
        <!-- Enable debug output -->
        <option name="debug">true</option>
    </defaults>

    <users>
        <user id="root">
            <!-- Enable colored output for user "root" -->
            <option name="color_log">true</option>
        </user>

        <user id="scox">
             <!-- Disable debug output for user "scox" -->
             <option name="debug">false</option>
        </user>
    </users>

    <devices>
        <device id="mydevice">
            <!-- Wait 15 seconds instead of the default 10 seconds for "mydevice" to be detected -->
            <option name="probe_timeout">15</option>
        </device>
    </devices>

    <services>
        <service id="su">
            <!-- Disable pam_usb for "su" ("su" will ask for a password as usual) -->
            <option name="enable">false<option>
       </service>
    </services>
</configuration>

Devices

Name Type Description Example
id Attribute Arbitrary device name MyDevice
vendor Element Device's vendor name SanDisk Corp.
model Element Device's model name Cruzer Titanium
serial Element Serial number of the device SNDKXXXXXXXXXXXXXXXX
volume_uuid Element UUID of the device's volume used to store pads 6F6B-42FC

Note:

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).

Example:

<device id="MyDevice">
    <vendor>SanDisk Corp.</vendor>
    <model>Cruzer Titanium</model>
    <serial>SNDKXXXXXXXXXXXXXXXX</serial>
    <volume_uuid>6F6B-42FC</volume_uuid>
</device>

Users

Name Type Description Example
id Attribute Login of the user root
device Element id of the device associated to the user MyDevice
agent Element Agent commands, for use with pamusb-agent

Note that one <user> can have multiple <device> (from v0.8.5 up).

Agent

The agent is to be run as system service. If you installed by using the debian package it will automatically be configured as systemd service unit. In case you use another init / service management you will need to set it up yourself before any event configuration will take effect.

Name Type Description
env Attribute Environment variable for the command. For multiple environment variables use multiple env tags.
cmd Attribute Agent command, associated with env tags in the same agent element. Multiple/chained cmd elements supported.

Example:

<user id="scox">
    <device>MyDevice</device>

    <!-- When the user "scox" removes the usb device, lock the screen and pause beep-media-player -->
    <agent event="lock">
        <env>DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus</env>
        <env>HOME=/home/scox</env>
        <cmd>gnome-screensaver-command --lock</cmd>
        <cmd>sleep 5</cmd>
        <cmd>pkill -SIGSTOP -u 1000</cmd>
    </agent>
    <agent event="lock">
        <cmd>beep-media-player --pause</cmd>
    </agent>

    <!-- Resume operations when the usb device is plugged back and authenticated -->
    <agent event="unlock">
        <env>DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus</env>
        <env>HOME=/home/scox</env>
        <cmd>pkill -SIGCONT -u 1000</cmd>
        <cmd>sleep 5</cmd>
        <cmd>gnome-screensaver-command --deactivate</cmd>
    </agent>
    <agent event="unlock">
        <cmd>beep-media-player --play</cmd>
    </agent>
</user>

For systemd based distributions you can use loginctl lock-session as lock <cmd>, to unlock you can use loginctl unlock-session.

Services

Name Type Description Example
id Attribute Name of the service su

Example:

<service id="su">
    <!--
       Here you can put service specific options such as "enable", "debug" etc.
       See the options section of this document.
    -->
</service>

Location of the configuration file

By default, pam_usb.so and its tools will look for the configuration file at /etc/security/pam_usb.conf.

If you want to use a different location, you will have to use the -c flag.

# /etc/pam.d/system-auth
auth    sufficient      pam_usb.so -c /some/other/path.conf
auth    required        pam_unix.so nullok_secure

You will also have to use the -c option when calling pam_usb's tools.

pamusb-agent -c /some/other/path.conf

Example configuration

  1. Insert a removable block device

  2. Add necessary device configuration into /etc/security/pam_usb.conf by running:

sudo pamusb-conf --add-device=<devicename>

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.)

You can do this for multiple devices obviously.

  1. Add necessary user configuration into /etc/security/pam_usb.conf by running:
sudo pamusb-conf --add-user=<username>

where <username> is a valid Unix user name.

If you added multiple devices you can repeat this command to choose an additional device for this user (from v0.8.5 up).

  1. Tweak /etc/security/pam_usb.conf manually as desired. Link devices and users, etc.

If you use one time pads (default), you need to do the following:

  1. Run /usr/bin/pamusb-check --debug <username>

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 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.

  1. Add proper PAM configuration into /etc/pam.d/common-auth as described in Getting Started. 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.
  2. 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.
Clone this wiki locally