pam_usb/doc/CONFIGURATION.md

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

The syntax is the following:

<configuration>
<defaults>
<!-- default options -->
</defaults>
<devices>
<!-- devices definitions -->
</devices>
<users>
<!-- users definitions -->
</users>
<services>
<!-- services definitions -->
</services>
</configuration>

Options

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

Name	Type	Default	Description

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

<tr>
    <td>id</td>
    <td>Attribute</td>
    <td>Arbitrary device name</td>
    <td>MyDevice</td>
</tr>
<tr>
    <td>vendor</td>
    <td>Element</td>
    <td>device's vendor name</td>
    <td>SanDisk Corp.</td>
</tr>
<tr>
    <td>model</td>
    <td>Element</td>
    <td>device's model name</td>
    <td>Cruzer Titanium</td>
</tr>
<tr>
    <td>serial</td>
    <td>Element</td>
    <td>serial number of the device</td>
    <td>SNDKXXXXXXXXXXXXXXXX</td>
</tr>
<tr>
    <td>volume_uuid</td>
    <td>Element</td>
    <td>UUID of the device's volume used to store pads</td>
    <td>6F6B-42FC</td>
</tr>

Name	Type	Description	Example

Example:

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

Users

<tr>
    <th>Name</th>
    <th>Type</th>
    <th>Description</th>
    <th>Example</th>
</tr>
<tr>
    <td>id</td>
    <td>Attribute</td>
    <td>Login of the user</td>
    <td>root</td>
</tr>
<tr>
    <td>device</td>
    <td>Element</td>
    <td>id of the device associated to the user</td>
    <td>MyDevice</td>
</tr>
<tr>
    <td>agent</td>
        <td>env</td>
        <td>Element</td>
        <td>An environment variable for the command. For multiple variables use multiple env tags</td>
        <td>cmd</td>
        <td>Element</td>
        <td>Agent command, associated with env tags in the same agent element</td>
    <td>Element</td>
    <td>Agent commands, for use with pamusb-agent</td>
</tr>

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>
</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>gnome-screensaver-command --deactivate</cmd>
</agent>
<agent event="unlock">
<cmd>beep-media-player --play</cmd>
</agent>
</user>

Services

<tr>
    <td>id</td>
    <td>Attribute</td>
    <td>Name of the service</td>
    <td>su</td>
</tr>

Name	Type	Description	Example

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/common-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