Debian Codegraph @

doc/README.eventmgr

raw
1 Using the Card Event Manager
2 ----------------------------
3
4 PAM-PKCS11 includes a tool "card_eventmgr" that can be used to
5 monitor the status of the card reader and dispatch actions on several
6 events. This program can be used for several actions, like screen lock on
7 card removal.
8
9 Note that this program has no interaction with pam-pkcs11: is just a
10 card status monitor. It's up to the sysadmin to define and configure
11 actions to take on events.
12
13 To invoke the program, just type "card_eventmgr".
14
15 Several command lines are recognized:
16
17 - debug - to enable debugging. Defaults to unset
18 - daemon - to run as daemon. If debug is unset, also detach from tty.
19 Default to unset
20 - timeout=<msecs> - time in msec between two consecutive status poll.
21 Defaults to 1000 (1 second)
22 - config_file=<file> - configuration file to use. Defaults to
23 /etc/pam_pkcs11/card_eventmgr.conf
24
25 Structure of configuration file is described below:
26
27 card_eventmgr {
28
29 # Run in background.
30 daemon = false;
31
32 # show debug messages
33 debug = false;
34
35 # polling time in mili-seconds
36 timeout = 1000;
37
38 #
39 # list of events and actions
40
41 # Card inserted
42 event card_insert {
43 # what to do if an action fail?
44 # ignore : continue to next action
45 # return : end action sequence
46 # quit : end program
47 on_error = ignore ;
48
49 # You can enter several, comma-separated action entries
50 # they will be executed in turn
51 action = "/usr/bin/play /usr/share/sounds/warning.wav",
52 "/usr/X11R6/bin/xscreensaver-command -deactivate";
53 }
54
55 # Card has been removed
56 event card_remove {
57 on_error = ignore;
58 action = "/usr/bin/play /usr/share/sounds/error.wav",
59 "/usr/X11R6/bin/xscreensaver-command -lock";
60 }
61
62 # Too much time locked session
63 event timeout {
64 }
65 }
66
67 As you can see, on each event you can define a list of actions, and what
68 to do if an action fails.
69
70 SECURITY ISSUES:
71
72 The best way to start card monitoring is at user login into the system.
73 If so, note that all event commands will be executed with user privileges.
74 So is up to the user to take care that he has the rights to execute the
75 desired actions.
76
77 EXAMPLE: use xscreensaver to lock the screen at card removal
78
79 you can use the provided configuration sample file.
80 Just add to your .xsession or KDE/GNOME Autostart directory
81 an invocation to card_eventmgr in daemon mode.
82
83 Additionally you can add this entry to /etc/pam.d/xscreensaver
84 configuration:
85
86 #%PAM-1.0
87
88 # Red Hat says this is right for them, as of 7.3:
89 auth sufficient pam_pkcs11.so debug config_file=/etc/pam_pkcs11/pam_pkcs11.conf
90 auth required pam_stack.so service=system-auth
91
92 # This is what we were using before:
93 # auth required pam_pwdb.so shadow nullok
94 At pam-pkcs11-0.4.3 handling of timeout event is not managed yet
95
96 In this case, when the card is removed the X screen will be locked. When
97 the card is re-inserted, screen will prompt for the card PIN, check it and
98 if access is granted the screen will unlock.