Debian Codegraph @

README

raw
1 pam-afs-session 2.6
2 (PAM module for AFS PAGs and tokens)
3
4 Written by Russ Allbery <[email protected]>
5
6 Copyright 2015 Russ Allbery <[email protected]>. Copyright 2005, 2006,
7 2007, 2008, 2010, 2011 The Board of Trustees of the Leland Stanford
8 Junior University. This software is distributed under a BSD-style
9 license. Plese see the section LICENSE below for more information.
10
11 BLURB
12
13 pam-afs-session is a PAM module intended for use with a Kerberos PAM
14 module to obtain an AFS PAG and AFS tokens on login. It puts every new
15 session in a PAG regardless of whether it was authenticated with
16 Kerberos and either uses Heimdal's libkafs or runs a configurable
17 external program to obtain tokens. It supports using Heimdal's libkafs
18 or OpenAFS's libkopenafs for the AFS interface and falls back to an
19 internal implementation if libkafs isn't available.
20
21 DESCRIPTION
22
23 pam-afs-session is a PAM module that isolates each login in a separate
24 AFS PAG (so that they will not trample on each other's AFS tokens) and
25 supports either running an external program to obtain AFS tokens from a
26 Kerberos ticket cache or using Heimdal's libkafs library. It does not
27 obtain tickets itself and must be used in conjunction with a Kerberos
28 PAM module to obtain tokens (setting up PAGs can be done without any
29 Kerberos implementations). It provides only the setcred and session PAM
30 functions.
31
32 There are two ways this module can obtain tokens:
33
34 * If you have Heimdal's libkafs library available, the module can call
35 libkafs's krb5_afslog function to obtain tokens directly. If you are
36 using Heimdal and obtaining tokens from Kerberos tickets, this is the
37 recommended configuration, since it means the PAM module doesn't have
38 to fork an external process. If built with Heimdal's libkafs, this
39 will be the default unless program is set in the module
40 configuration.
41
42 * Otherwise, the module will run an arbitrary external program to
43 obtain tokens. This is the most flexible option, works with MIT
44 Kerberos in conjunction with the aklog program from OpenAFS or the
45 afslog program from Heimdal, and can support programs that obtain AFS
46 tokens via some means other than a Kerberos ticket cache created on
47 login.
48
49 For the AFS system call layer, pam-afs-session supports linking with the
50 Heimdal libkafs library or OpenAFS's libkopenafs library. As a
51 fallback, and to support a low-dependency build, it also comes with a
52 simple AFS system call implementation for Linux, Mac OS X, Solaris, or
53 platforms that use syscall to call AFS functions. It can also link with
54 the older OpenAFS libraries when libkopenafs isn't available.
55
56 The module can optionally be linked with Kerberos libraries to obtain
57 configuration information from krb5.conf, to support the kdestroy
58 option, and to use libkafs's functions for obtaining tokens.
59
60 This module does not support getting tokens for the rmtsys AFS network
61 redirection interface (generally used with the NFS translator).
62
63 pam-afs-session is primarily tested on Linux. I rely on reports from
64 users to ensure it continues working on other platforms. Please let me
65 know if any problems you run into.
66
67 REQUIREMENTS
68
69 The PAM implementations on Linux, Solaris, Mac OS X, HP-UX, and AIX are
70 supported, although the module is primarily tested on Linux and only
71 lightly tested (and not at all by me personally) on the other platforms.
72 Use on platforms with other PAM implementations, such as IRIX or the
73 *BSDs, will require more porting and will not currently work. Patches
74 are welcome.
75
76 The module is written in C and should hopefully build on any system with
77 an adequate PAM library that Libtool supports.
78
79 Either Heimdal's libkafs or OpenAFS's libkopenafs are the preferred ways
80 of making AFS system calls. If neither are present during compile time,
81 pam-afs-session will attempt to fall back on a built-in AFS system call
82 layer. To use the built-in AFS system call interface on Linux, Mac OS
83 X, and Solaris 11, the system must run a new enough version of OpenAFS
84 or Arla to support AFS system calls through ioctl on a file in /proc or
85 /dev. On other systems with a simple system call interface, configure
86 must be able to find the AFS header afs/param.h in order to get the
87 system call numbers for that platform. On AIX and IRIX, configure will
88 attempt to locate the necessary OpenAFS libraries for lsetpag (either
89 libafsauthent or libsys) but will not support deleting tokens at the end
90 of a session.
91
92 The module can optionally use Heimdal's libkafs library to obtain tokens
93 as well as create the PAG. If you are using Heimdal and obtaining
94 tokens from Kerberos tickets, this is the recommended configuration,
95 since it means that the PAM module doesn't have to fork an external
96 process. For other users, an external aklog program that obtains tokens
97 is necessary (and not provided by this module).
98
99 To obtain configuration information from krb5.conf and to support the
100 kdestroy option, either MIT Kerberos or Heimdal are required.
101
102 Testing the module requires a system with AFS installed and working so
103 that the PAG creation and manipulation can be tested. Running the
104 complete test suite also requires that you have an existing ticket cache
105 and working aklog program. Those portions of the test suite will be
106 skipped if AFS or a Kerberos ticket cache do not appear to be available.
107
108 To run the POD test suite, you must have the Perl 5.006 or later and the
109 modules Test::More and Test::Pod installed. Test::More comes with Perl
110 5.8 or later. Test::Pod is available from CPAN and currently must be
111 installed separately, but the POD tests will be skipped without
112 interfering with the rest of the tests if it's not installed.
113
114 To check spelling in the POD documentation, Pod::Spell (available from
115 CPAN) and either aspell or ispell with the american dictionary are also
116 required. The user's path is searched for aspell or ispell and aspell
117 is preferred. Spelling tests are disabled by default since spelling
118 dictionaries differ too much between systems. To enable those tests,
119 set RRA_MAINTAINER_TESTS to a true value.
120
121 To bootstrap from a Git checkout, or if you change the Automake files
122 and need to regenerate Makefile.in, you will need Automake 1.11 or
123 later. For bootstrap or if you change configure.ac or any of the m4
124 files it includes and need to regenerate configure or config.h.in, you
125 will need Autoconf 2.64 or later. Perl is also required to generate the
126 manual pages from a fresh Git checkout.
127
128 COMPILING AND INSTALLING
129
130 To build the module, just run:
131
132 ./configure
133 make
134
135 Kerberos support is enabled by default if configure can find Kerberos
136 libraries. If your Kerberos libraries aren't installed in a location
137 found by your compiler by default and krb5-config isn't on your PATH,
138 use the --with-krb5=PATH option to configure. The Kerberos libraries
139 will then be expected in PATH/lib and the headers in PATH/include.
140
141 To specify a particular krb5-config script to use, either set the
142 KRB5_CONFIG environment variable or pass it to configure like:
143
144 ./configure KRB5_CONFIG=/path/to/krb5-config
145
146 To not use krb5-config and force library probing even if there is a
147 krb5-config script on your path, set KRB5_CONFIG to a nonexistent path:
148
149 ./configure KRB5_CONFIG=/nonexistent
150
151 To disable Kerberos support, even if you have Kerberos libraries
152 available, pass --without-krb5 to configure.
153
154 By default, the first aklog program found on the PATH will be compiled
155 into the module as the default aklog program to run. This can be
156 overridden by the program PAM option. To specify an explicit path to
157 aklog, use:
158
159 ./configure --with-aklog=/path/to/aklog
160
161 instead.
162
163 To install the module into /usr/local/lib/security and the man page into
164 /usr/local/share/man/man5, run:
165
166 make install
167
168 You can change the installation locations with the --prefix, --mandir,
169 and --libdir options to configure. The module will normally be
170 installed in a subdirectory of $libdir named security, but if --prefix
171 is set to /usr (rather than /usr/local, the default), the module will be
172 installed in /lib/security (or /lib32/security or /lib64/security if
173 they exist) to match the default PAM configuration. Alternately, you
174 can simply copy pam_afs_session.so to whatever directory you use for PAM
175 modules. On Solaris, you will need to make the module executable.
176
177 By default, if libkafs or libkopenafs are available, pam-afs-session
178 will use them in preference to its own system call implementation. If
179 for some reason you want to build pam-afs-session without a dependency
180 on those libraries even though you have them installed, pass the
181 --without-libkafs flag to configure.
182
183 If you are building this module without libkafs on a platform other than
184 Linux, configure needs to find the AFS header afs/param.h. If this is
185 not in the normal include path, pass the --with-afs-headers option to
186 configure to point the compiler at the correct path. For example, if
187 your AFS headers are in /usr/afsws/include, run:
188
189 ./configure --with-afs-headers=/usr/afsws/include
190
191 instead.
192
193 You can pass the --enable-reduced-depends flag to configure to try to
194 minimize the shared library dependencies encoded in the binaries. This
195 omits from the link line all the libraries included solely because
196 libkafs or the Kerberos libraries depend on them and instead links the
197 programs only against libraries whose APIs are called directly. This
198 will only work with shared libraries and will only work on platforms
199 where shared libraries properly encode their own dependencies (such as
200 Linux). It is intended primarily for building packages for Linux
201 distributions to avoid encoding unnecessary shared library dependencies
202 that make shared library migrations more difficult. If none of the
203 above made any sense to you, don't bother with this flag.
204
205 TESTING
206
207 pam-afs-session comes with a test suite, which you can run after
208 building pam-afs-session with:
209
210 make check
211
212 If a test case fails, please run the that individual test case with
213 verbose output using:
214
215 tests/runtests -o <name-of-test>
216
217 and send me the output when reporting the problem.
218
219 CONFIGURING
220
221 Just installing the module does not enable it or change anything about
222 your system authentication configuration. You have to add the module to
223 your PAM configuration, generally in the session group and possibly in
224 the auth group as well. See the platform-specific instructions below.
225
226 On all platforms, options can be put after the module name in the PAM
227 configuration file. This is useful if you don't have Kerberos libraries
228 available or if you want different configurations for different
229 services.
230
231 If Kerberos support was enabled, configuration options may also be put
232 in the krb5.conf file used by your Kerberos libraries (usually
233 /etc/krb5.conf or /usr/local/etc/krb5.conf) instead or in addition to
234 the PAM configuration. See the man page for more details. This is
235 recommended for general system configuration, since the krb5.conf
236 configuration syntax is a little nicer and more flexible.
237
238 See the files in the examples directory for examples of PAM
239 configuration for various operating systems. Contributions for
240 additional operating systems are welcome.
241
242 Linux
243
244 To use it in conjunction with pam_krb5 on a Debian system, put something
245 like:
246
247 auth [success=ok default=1] pam_krb5.so
248 auth [default=done] pam_afs_session.so program=/usr/bin/aklog
249 auth required pam_unix.so try_first_pass nullok_secure
250
251 in /etc/pam.d/common-auth and something like:
252
253 session optional pam_krb5.so
254 session required pam_afs_session.so program=/usr/bin/aklog
255
256 in /etc/pam.d/common-session. The program= setting is optional if
257 /usr/bin/aklog was in your path when the module was compiled or was
258 specified via the --with-aklog option to configure.
259
260 You may want to stack your Kerberos PAM module and the Unix module
261 differently, but note that this module should always run after the
262 Kerberos PAM module. If there is no ticket cache available in the PAM
263 environment, it will succeed silently.
264
265 On Red Hat systems, modify /etc/pam.d/system-auth instead; it contains
266 all of the configuration for the different stacks.
267
268 Be aware that the pam_keyinit module can have a bad interaction with
269 this module. pam_keyinit initializes a new kernel keyring and will
270 remove the keyring created by pam_afs_session to represent your PAG and
271 hold your tokens. pam_afs_session will attempt to detect this and add
272 the PAG and tokens back, but to do so it must run after pam_keyinit in
273 the session stack. To be safe, you may want to remove this PAM module
274 unless you're using it.
275
276 Note that this is not an authentication module and will always return
277 PAM_SUCCESS to any authentication attempt, so never make this module
278 sufficient in your authentication stack. It's only listed as an auth
279 module because it provides a pam_setcred implementation and some
280 programs need to call pam_setcred rather than pam_open_session (screen
281 savers, for instance, to refresh credentials).
282
283 Solaris
284
285 Solaris doesn't support the [] keywords that Linux PAM does, so if you
286 want to mark the Kerberos PAM module as sufficient and fall back on the
287 Unix module only if it fails, you won't be able to easily run
288 pam_afs_session in the auth group. For most applications, this isn't a
289 problem; running pam_afs_session only from the session group with
290 something like:
291
292 other session required /usr/local/lib/security/pam_afs_session.so
293 minimum_uid=100 retain_after_close
294
295 (all on one line) in /etc/pam.conf will be sufficient. Make sure this
296 line is after the Kerberos PAM module's session call.
297
298 However, note that login and dtlogin, at least under Solaris 10,
299 apparently call pam_open_session before pam_setcred, and the
300 open_session function of the native Kerberos PAM module doesn't set up
301 the ticket cache. This means that calling pam_afs_session only in the
302 session group won't work, since it will be called before the setcred
303 function of the Kerberos PAM module and hence won't have a ticket cache
304 available yet. There are two possible solutions: replace the native
305 Kerberos PAM module with another module, such as:
306
307 http://www.eyrie.org/~eagle/software/pam-krb5/
308
309 that does the same thing in open_session as in setcred, or also call
310 pam_afs_session from the auth group:
311
312 login auth required /usr/local/lib/security/pam_afs_session.so
313 minimum_uid=100
314
315 after the Kerberos PAM module (and likewise for dtlogin). This means
316 that you cannot use sufficient in the auth group for the Kerberos PAM
317 module, since that will then abort the group before pam_afs_session
318 runs.
319
320 See the man page for pam.conf on Solaris for more configuration
321 information.
322
323 HP-UX
324
325 HP-UX configuration is very similar to Solaris. Something like:
326
327 dtaction session required /usr/lib/security/pam_afs_session.so
328 dtlogin session required /usr/lib/security/pam_afs_session.so
329 login session required /usr/lib/security/pam_afs_session.so
330 OTHER session required /usr/lib/security/pam_afs_session.so
331
332 will use pam-afs-session for most login sessions.
333
334 Mac OS X
335
336 For Mac OS X, PAM isn't used for system login and is therefore mostly
337 useful for remote ssh. To use this module with sshd, add it to the
338 session group of the sshd PAM configuration, and it will then obtain
339 tokens with forwarded tickets via GSS-API or tickets obtained via
340 KerberosAuthentication.
341
342 Note that PAGs are not supported on Mac OS X, so you will need to add
343 the "nopag" parameter to the PAM configuration for this module. Note
344 also that while the latest Mac OS X ssh daemon supports GSS-API
345 authentication, it apparently doesn't make the forwarded tickets
346 available to the PAM stack, so pam-afs-session cannot properly set up
347 tokens during GSS-API login.
348
349 IMPLEMENTATION NOTES
350
351 pam-afs-session supports three basic usage patterns: creating a new
352 session using either pam_open_session or pam_setcred(PAM_ESTABLISH_CRED)
353 (or both), closing a session with pam_close_session or
354 pam_setcred(PAM_DELETE_CRED), and refreshing credentials with
355 pam_setcred(PAM_REINITIALIZE_CRED). In general, the same behavior
356 occurs whether using the pam_*_session interface or the pam_setcred
357 interface, since some PAM-using programs call one and some call the
358 other. In all cases, pam-afs-session will log an error and then
359 successfully exit if AFS doesn't appear to be running (checked with the
360 k_hasafs interface).
361
362 pam-afs-session stores a PAM data key named "pam_afs_session" once it
363 has successfully created a PAG and a token. If this key is present in
364 the PAM data when pam_open_session or pam_setcred with the
365 PAM_ESTABLISH_CRED flag is called, it will successfully do nothing to
366 keep from doing duplicate work. Otherwise, it will always create a PAG
367 and then will either call krb5_afslog or run an external program to
368 obtain tokens provided that the environment variable KRB5CCNAME is set
369 in the PAM environment.
370
371 If libkafs was found and used at compile time and if krb5_afslog is
372 available, the default is to run krb5_afslog to obtain tokens.
373 Otherwise, the default is to run whatever aklog program was found at
374 compile time. If program is set explicitly in the configuration,
375 pam-afs-session will always run that program rather than calling
376 krb5_afslog.
377
378 When pam_close_session or pam_setcred(PAM_DELETE_CRED) is called,
379 pam-afs-session will destroy the user's tokens only if the PAM data key
380 "pam_afs_session" is present (meaning that pam-afs-session previously
381 obtained tokens). This check is present to avoid deleting tokens when
382 session initialization failed, since in that case no new PAG may have
383 been created and we may be deleting tokens that are not ours to delete.
384
385 pam_setcred(PAM_REINITIALIZE_CRED) is treated similarly to the opening
386 of a new session except that no PAG is created. Instead, only the
387 program to obtain tokens is run, provided that KRB5CCNAME is set in the
388 PAM environment. This interface is used by programs such as screen
389 savers and lockers to refresh a user's credentials.
390
391 pam-afs-session requires that the user (obtained via pam_get_user)
392 exists in the local passwd file or equivalent (using getpwnam). If
393 running an external program, the program is run under that user's UID
394 and primary GID. If calling krb5_afslog, that user's UID is used for
395 the "AFS ID" field in the tokens display (which is entirely cosmetic).
396
397 HOMEPAGE AND SOURCE REPOSITORY
398
399 The pam-afs-session web page at:
400
401 http://www.eyrie.org/~eagle/software/pam-afs-session/
402
403 will always have the current version of this package, the current
404 documentation, and pointers to any additional resources.
405
406 pam-afs-session is maintained using Git. You can access the current
407 source by cloning the repository at:
408
409 git://git.eyrie.org/afs/pam-afs-session.git
410
411 or view the repository via the web at:
412
413 http://git.eyrie.org/?p=afs/pam-afs-session.git
414
415 HISTORY AND ACKNOWLEDGEMENTS
416
417 Some of the ideas behind this PAM module (although not the code) are
418 taken from the libpam-openafs-session Debian package written by Sam
419 Hartman and the pam_afs2 module written by Douglas Engert. Thanks to
420 both of them for their previous work. Any errors in this implementation
421 are mine.
422
423 The Linux system call layer was based on inspection of the code in
424 OpenAFS and on discussions with Jeffrey Hutzelman on how best to
425 implement an AFS system call layer and on how the pieces work. I
426 couldn't have written this code without his explanations.
427
428 Thanks to Douglas Engert for an initial code review, for Solaris
429 porting, for suggesting the always_aklog and aklog_homedir options, and
430 for catching various other problems and missing features.
431
432 Thanks to Sean O'Malley for additional Solaris porting information and
433 for testing with the Sun C compiler.
434
435 Thanks to Joe Buehler for porting and testing on HP-UX.
436
437 Thanks to Markus Moeller for multiple patches and suggestions for
438 improved portability for pam-krb5, from which this module has also
439 benefitted.
440
441 LICENSE
442
443 The pam-afs-session package as a whole is covered by the following
444 copyright statement and license:
445
446 Copyright 2015 Russ Allbery <[email protected]>
447 Copyright 2005, 2006, 2007, 2008, 2009, 2010, 2011
448 The Board of Trustees of the Leland Stanford Junior University
449
450 Permission is hereby granted, free of charge, to any person obtaining
451 a copy of this software and associated documentation files (the
452 "Software"), to deal in the Software without restriction, including
453 without limitation the rights to use, copy, modify, merge, publish,
454 distribute, sublicense, and/or sell copies of the Software, and to
455 permit persons to whom the Software is furnished to do so, subject to
456 the following conditions:
457
458 The above copyright notice and this permission notice shall be
459 included in all copies or substantial portions of the Software.
460
461 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
462 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
463 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
464 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
465 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
466 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
467 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
468
469 All individual files without an explicit exception below are released
470 under this license. Some files may have additional copyright holders as
471 noted in those files. There is detailed information about the licensing
472 of each file in the LICENSE file in this distribution.
473
474 Some files in this distribution are individually released under
475 different licenses, all of which are compatible with the above general
476 package license but which may require preservation of additional
477 notices. All required notices are preserved in the LICENSE file. Each
478 file intended for copying into other software packages contains a
479 copyright and license notice at the top or bottom of the file. Please
480 take note of any attribution and notice requirements specified in that
481 license.