Browse Source

Update & re-style docs

master
Pekka Helenius 4 years ago
parent
commit
25e22af95d
1 changed files with 117 additions and 208 deletions
  1. +117
    -208
      doc/CONFIGURATION.md

+ 117
- 208
doc/CONFIGURATION.md View File

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

Loading…
Cancel
Save