diff --git a/doc/CONFIGURATION.md b/doc/CONFIGURATION.md index a5943a1..65400ac 100644 --- a/doc/CONFIGURATION.md +++ b/doc/CONFIGURATION.md @@ -30,96 +30,25 @@ The syntax is the following: ``` -Options -------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDefaultDescription
enableBooleantrueEnable pam_usb
debugBooleanfalseEnable debug messages
quietBooleanfalseQuiet mode
color_logBooleantrueEnable colored output
one_time_padBooleantrueEnable the use of one time pads
deny_remoteBooleantrueDeny access from remote host (ssh)
probe_timeoutTime10sTime to wait for the volume to be detected
pad_expirationTime1hTime between pads regeneration
hostnameStringComputer's hostnameMust be unique accross computers using the same device
system_pad_directoryString.pamusbRelative path to the user's home used to store one time pads
device_pad_directoryString.pamusbRelative path to the device used to store one time pads
- -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 @@ -129,7 +58,7 @@ Example: - + @@ -158,54 +87,20 @@ Example: ``` -Devices -------- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionExample
idAttributeArbitrary device nameMyDevice
vendorElementdevice's vendor nameSanDisk Corp.
modelElementdevice's model nameCruzer Titanium
serialElementserial number of the deviceSNDKXXXXXXXXXXXXXXXX
volume_uuidElementUUID of the device's volume used to store pads6F6B-42FC
- -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 @@ -216,52 +111,30 @@ Example: ``` -Users ------ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
NameTypeDescriptionExample
idAttributeLogin of the userroot
deviceElementid of the device associated to the userMyDevice
agentenvElementAn environment variable for the command. For multiple variables use multiple env tagscmdElementAgent command, associated with env tags in the same agent elementElementAgent commands, for use with pamusb-agent
- -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 MyDevice - + @@ -272,7 +145,7 @@ Example: beep-media-player --pause - + DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/1000/bus @@ -285,26 +158,15 @@ Example: ``` -Services --------- - - - - - - - - - - - - - - - -
NameTypeDescriptionExample
idAttributeName of the servicesu
- -Example: +---------- + +## Services + +| Name | Type | Description | Example | +|------|-----------|---------------------|---------| +| `id` | Attribute | Name of the service | `su` | + +### Example: ```xml @@ -315,17 +177,64 @@ Example: ``` +---------- + 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. - # /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= +``` + +where `` is a valid Unix user name. + +* **3)** Add necessary device configuration into `/etc/security/pam_usb.conf` by running: + +``` +sudo pamusb-conf --add-device= +``` + +where `` 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 ` + +where `` 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/.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.