Voir la source de Security/PamUsb/GettingStarted

= Getting Started =

Setting up pam_usb requires the following, [[Security/PamUsb/Install|Install]]:

# Set up devices and users
# Configuring PAM for system authentication
# (Optional) Configuring {{app|pamusb-agent}} to run programs when the device is inserted or removed

== Setting up Devices and Users ==

Once you've connected your USB device to the computer, use {{app|pamusb-conf}} to add it to the configuration file:

<pre>
pamusb-conf --add-device masterkey
Please select the device you wish to add.
* Using "USB Flash Disk (FBF1101121100745)" (only option)

Which volume would you like to use for storing data ?
0) /dev/sdd1 (UUID: 335F405C0A8030B0)
1) /dev/sdd3 (UUID: 3ea9b653-a346-4827-85a8-b809bcec4028)
2) /dev/sdd2 (UUID: c7467fbf-6ef2-40ac-9ce1-d019292fc266)

[0-2]: 1

Name            : masterkey
Vendor          : USB
Model           : Flash Disk
Serial          : FBF1101121100745
UUID            : 3ea9b653-a346-4827-85a8-b809bcec4028

Save to /etc/pamusb.conf ?
[Y/n] y
Done.
</pre>

{{Admon/note|Device Name|Device name can be any arbitrary name you'd like. Also, you can add as many devices as you want.}}

Next, configure users you want to be able to authenticate with pam_usb:

<pre>
pamusb-conf --add-user root
Which device would you like to use for authentication ?
* Using "masterkey" (only option)

User            : root
Device          : masterkey

Save to /etc/pamusb.conf ?
[Y/n] 
Done.
</pre>
<pre>
pamusb-conf --add-user didier
Which device would you like to use for authentication ?
* Using "masterkey" (only option)

User            : didier
Device          : masterkey

Save to /etc/pamusb.conf ?
[Y/n] 
Done.
</pre>

== Check the configuration ==

You can run {{app|pamusb-check}} anytime to check if everything is correctly worked.
This tool will simulate an authentication request (requires your device to be connected, otherwise it will fail).

<pre>
pamusb-check didier
* Authentication request for user "didier" (pamusb-check)
* Device "masterkey" is connected (good).
* Performing one time pad verification...
* Access granted.
</pre>

== Setting up the PAM module ==

To add pam_usb into the system authentication process, we need to edit <path>/etc/pam.d/common-auth</path>
{{Admon/note|If you are using RedHat or Fedora|This file can be known as /etc/pam/system-auth.}}

Your default PAM common-auth configuration should include the following line:

 auth    required        pam_unix.so nullok_secure

This is a current standard which uses passwords to authenticate a user.

Alter your /etc/pam.d/common-auth configuration to:

 auth    sufficient      pam_usb.so
 auth    required        pam_unix.so nullok_secure

The ''suffient'' keyword means that if pam_usb allows the authentication, then no password will be asked.
If the authentication fails, then the default password-based authentication will be used as fallback.

If you change it to ''required'', it means that *both* the USB flash drive and the password will be required to grant
access to the system.

At this point, you should be able to authenticate with the relevant USB device plugged-in.
<pre>
$ su -
* pam_usb v0.5.0
* Authentication request for user "root" (su-l)
* Device "masterkey" is connected (good).
* Performing one time pad verification...
* Regenerating new pads...
* Access granted.
# 
</pre>

== Agent ==

The pam_usb agent ({{app|pamusb-agent}}) allows you to automatically execute commands
upon locking and unlocking events. Those events are generated when you insert or
remove your authentication device.
To configure the commands, you have to edit pam_usb's configuration file
(<path>/etc/pamusb.conf</path>) and add agent entries into your user section.

For instance, you could automatically start your screensaver as soon as you
remove the device, and deactivate it when you plug the device back.

'''GNOME (gnome-screensaver)''':
<syntaxhighlight lang="xml">
<user id="didier">
  <device>didier-key</device>
  <agent event="lock">gnome-screensaver-command --lock</agent>
  <agent event="unlock">gnome-screensaver-command --deactivate</agent>
</user>
</syntaxhighlight>

'''KDE3 (kscreensaver via DCOP)''':
<syntaxhighlight lang="xml">
<user id="didier">
  <device>didier-key</device>
  <agent event="lock">dcop kdesktop KScreensaverIface lock</agent>
  <agent event="unlock">dcop kdesktop KScreensaverIface quit</agent>
</user>
</syntaxhighlight>

'''KDE4 (kscreensaver via DBUS)''':
<syntaxhighlight lang="xml">
<user id="didier">
  <device>didier-key</device>
  <agent event="lock">qdbus org.freedesktop.ScreenSaver /ScreenSaver Lock</agent>
  <agent event="unlock">qdbus org.kde.screenlocker /MainApplication quit</agent>
</user>
</syntaxhighlight>
{{Admon/note|More commands|You can execute more commands by adding extra '''<nowiki><agent></nowiki>''' entries.}}

<pre>
$ ./pamusb-agent
pamusb-agent[6674]: pamusb-agent up and running.
pamusb-agent[6674]: Watching device "masterkey" for user "didier"
pamusb-agent[6674]: Device "masterkey" has been removed, locking down user "didier"...
pamusb-agent[6674]: Running "qdbus org.freedesktop.ScreenSaver /ScreenSaver Lock"

pamusb-agent[6674]: Running "ssh-add -D"
All identities removed.
pamusb-agent[6674]: Running "fusermount -u /home/didier/unsafe"
pamusb-agent[6674]: Locked.
pamusb-agent[6674]: Device "masterkey" has been inserted. Performing verification...
pamusb-agent[6674]: Executing "/usr/bin/pamusb-check --quiet --config=/etc/pamusb.conf --service=pamusb-agent didier"
pamusb-agent[6674]: Authentication succeeded. Unlocking user "didier"...
pamusb-agent[6674]: Running "qdbus org.kde.screenlocker /MainApplication quit"

pamusb-agent[6674]: Running "/home/didier/.kde/Autostart/ssh-add.sh"
pamusb-agent[6674]: Running "encfs /home/didier/.safe/ /home/didier/unsafe --extpass=ksshaskpass"
pamusb-agent[6674]: Unlocked.
</pre>

== F.A.Q. ==

{{Admon/faq|Sometimes pamusb stopped authenticating with the message "Pad checking failed".|In this case, issuing the following command helped me:
<pre>
rm ~/.pamusb/*
</pre>}}

= Fine Tuning =
Agent must
* Lock/Unlock screen  
* call [[Security/KDE/SSH/LoadKey| ssh-agent to load/unload private key without password]]
* [[Security/Crypt/Directory| encrypt/decrypt safe directories]] automatically.

Fichier <path>/etc/pamusb.conf</path>
<syntaxhighlight lang="xml">
<?xml version="1.0" ?><configuration>
        <!-- Default options -->
        <defaults>
                <option name="hostname">didier.home.org</option>
        </defaults>

        <!-- Device settings -->
        <devices>
                <device id="masterkey">
                        <vendor>USB</vendor>
                        <model>Flash Disk</model>
                        <serial>FBF1101121100745</serial>
                        <volume_uuid>c7467fbf-6ef2-40ac-9ce1-d019292fc266</volume_uuid>
                </device>
        </devices>

        <!-- User settings -->
        <users>
                <user id="root">
                        <device>masterkey</device>
                </user>
                <user id="didier">
                        <device>masterkey</device>
                        <agent event="lock">qdbus org.freedesktop.ScreenSaver /ScreenSaver Lock</agent>
                        <agent event="lock">ssh-add -D</agent>
                        <agent event="lock">fusermount -u /home/didier/unsafe</agent>
                        <agent event="unlock">qdbus org.kde.screenlocker /MainApplication quit</agent>
                        <agent event="unlock">/home/didier/.kde/Autostart/ssh-add.sh</agent>
                        <agent event="unlock">encfs /home/didier/.safe/ /home/didier/unsafe --extpass=ksshaskpass</agent>

                </user>
        </users>

        <!-- Services settings (e.g. gdm, su, sudo...) -->
        <services>
        </services>
</configuration>
</syntaxhighlight>

== Usefull scripts ==
Depending on your desktop environment, you have to add pamusb-agent to the list
of autostarted applications so it will be started automatically.

'''KDE Autostart script'''

We use <app>ksshaskpass</app> to make application password-less.

To use this script, you must create <path>/var/log/didier</path> directory, and change its owner and group before use. In that case :
<syntaxhighlight lang="bash">
mkdir /var/log/didier
chown didier:didier /var/log/didier
</syntaxhighlight>

File <path>/home/didier/.kde/Autostart/pamusb-agent.sh</path>
<syntaxhighlight lang="bash">
#!/bin/bash
nohup /usr/bin/pamusb-agent 1>/var/log/didier/pamusb-agent.log 2>&1 &
</syntaxhighlight>

'''Associate logrotate configuration file''' <path>/etc/logrotate.d/didier</path>
<syntaxhighlight lang="perl">
/var/log/didier/pamusb-agent.log {
        weekly
        compress
        missingok
        notifempty
        rotate 4
}
</syntaxhighlight>


'''GNOME''':
# Open System -> Preferences -> Sessions
# Select Startup Programs and press Add
# Enter pamusb-agent and press OK
# Press Close


There are many options available to fine configure pam_usb.

Check out the [[Security/PamUsb/ConfigurationFile| Configuration File]].