@ -30,96 +30,25 @@ The syntax is the following:
< / configuration > < / configuration >
``` ```
Options
-------
< table >
< tr >
< th > Name< / th >
< th > Type< / th >
< th > Default< / th >
< th > Description< / th >
< / tr >
< 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 >
< / table >
Example:
----------
## 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:
```xml ```xml
< configuration > < configuration >
@ -129,7 +58,7 @@ Example:
<!-- Enable debug output --> <!-- Enable debug output -->
< option name = "debug" > true< / option > < option name = "debug" > true< / option >
< / defaults > < / defaults >
< users > < users >
< user id = "root" > < user id = "root" >
<!-- Enable colored output for user "root" --> <!-- Enable colored output for user "root" -->
@ -158,54 +87,20 @@ Example:
< / configuration > < / configuration >
``` ```
Devices
-------
< table >
< tr >
< th > Name< / th >
< th > Type< / th >
< th > Description< / th >
< th > Example< / th >
< / tr >
< 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 >
< / table >
Example:
----------
## 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` |
### Example:
```xml ```xml
< device id = "MyDevice" > < device id = "MyDevice" >
@ -216,52 +111,30 @@ Example:
< / device > < / device >
``` ```
Users
-----
< table >
< 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 >
< / table >
Example:
----------
## Users
| Name | Type | Description | Example |
|----------|-----------|-------------------------------------------|------------|
| `id` | Attribute | Login of the user | `root` |
| `device` | Attribute | `id` of the device associated to the user | `MyDevice` |
| `agent` | Element | Agent commands, for use with pamusb-agent | |
### Agent
| Name | Type | Description |
|-------|-----------|-----------------------------------------------------------------------------------------------------|
| `env` | Attribute | An 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 |
### Example:
```xml ```xml
< user id = "scox" > < user id = "scox" >
< device > MyDevice< / device > < device > MyDevice< / device >
<!-- When the user "scox" removes the usb device, lock the screen and pause <!-- When the user "scox" removes the usb device, lock the screen and pause
beep-media-player --> beep-media-player -->
< agent event = "lock" > < agent event = "lock" >
@ -272,7 +145,7 @@ Example:
< agent event = "lock" > < agent event = "lock" >
< cmd > beep-media-player --pause< / cmd > < cmd > beep-media-player --pause< / cmd >
< / agent > < / agent >
<!-- Resume operations when the usb device is plugged back and authenticated --> <!-- Resume operations when the usb device is plugged back and authenticated -->
< agent event = "unlock" > < agent event = "unlock" >
< env > DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus< / env > < env > DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus< / env >
@ -285,26 +158,15 @@ Example:
< / user > < / user >
``` ```
Services
--------
< table >
< tr >
< th > Name< / th >
< th > Type< / th >
< th > Description< / th >
< th > Example< / th >
< / tr >
< tr >
< td > id< / td >
< td > Attribute< / td >
< td > Name of the service< / td >
< td > su< / td >
< / tr >
< / table >
Example:
----------
## Services
| Name | Type | Description | Example |
|------|-----------|---------------------|---------|
| `id` | Attribute | Name of the service | `su` |
### Example:
```xml ```xml
< service id = "su" > < service id = "su" >
@ -315,17 +177,64 @@ Example:
< / service > < / service >
``` ```
----------
Location of the configuration file 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` .
By default, ` pam_usb.so` `/etc/security/pam_usb.conf` .
If you want to use a different location, you will have to use the `-c` flag. 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
```
# /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
----------------------------------
**NOTE**: For detailed information, rely on repository wiki pages.
* **1)** Insert an USB block device
* **2)** 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.
* **3)** 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 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` .
If you use one time pads, you need to do the following:
* **5)** Manually mount USB block device partition. You need write access to the mounted partition.
* **6)** Run `/usr/bin/pamusb-check --debug --service=pamusb-agent <username>`
where `<username>` is associated with the USB block device.
You will also have to use the -c option when calling pam_usb's tools.
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.
pamusb-agent -c /some/other/path.conf
* **7)** Unmount the USB block device.
* **8)** Add proper PAM configuration into `/etc/pam.d/system-auth` as described above. 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.
Pekka Helenius
4 years ago