pam_group: Add ruser and luser options.
[dragonfly.git] / lib / pam_module / pam_ksu / pam_ksu.8
1 .\" Copyright (c) 2001 Mark R V Murray
2 .\" All rights reserved.
3 .\" Copyright (c) 2001 Networks Associates Technology, Inc.
4 .\" All rights reserved.
5 .\"
6 .\" This software was developed for the FreeBSD Project by ThinkSec AS and
7 .\" NAI Labs, the Security Research Division of Network Associates, Inc.
8 .\" under DARPA/SPAWAR contract N66001-01-C-8035 ("CBOSS"), as part of the
9 .\" DARPA CHATS research program.
10 .\"
11 .\" Redistribution and use in source and binary forms, with or without
12 .\" modification, are permitted provided that the following conditions
13 .\" are met:
14 .\" 1. Redistributions of source code must retain the above copyright
15 .\"    notice, this list of conditions and the following disclaimer.
16 .\" 2. Redistributions in binary form must reproduce the above copyright
17 .\"    notice, this list of conditions and the following disclaimer in the
18 .\"    documentation and/or other materials provided with the distribution.
19 .\" 3. The name of the author may not be used to endorse or promote
20 .\"    products derived from this software without specific prior written
21 .\"    permission.
22 .\"
23 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
24 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
27 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33 .\" SUCH DAMAGE.
34 .\"
35 .\" $FreeBSD: src/lib/libpam/modules/pam_ksu/pam_ksu.8,v 1.3 2002/12/12 08:19:47 ru Exp $
36 .\"
37 .Dd May 15, 2002
38 .Dt PAM_KSU 8
39 .Os
40 .Sh NAME
41 .Nm pam_ksu
42 .Nd Kerberos 5 SU PAM module
43 .Sh SYNOPSIS
44 .Op Ar service-name
45 .Ar module-type
46 .Ar control-flag
47 .Pa pam_ksu
48 .Op Ar options
49 .Sh DESCRIPTION
50 The Kerberos 5 SU authentication service module for PAM,
51 .Nm
52 for only one PAM category: authentication.
53 In terms of the
54 .Ar module-type
55 parameter, this is the
56 .Dq Li auth
57 feature.
58 The module is specifically designed to be used with the
59 .Xr su 1
60 utility.
61 .\" It also provides a null function for session management.
62 .Ss Kerberos 5 SU Authentication Module
63 The Kerberos 5 SU authentication component provides functions to verify
64 the identity of a user
65 .Pq Fn pam_sm_authenticate ,
66 and determine whether or not the user is authorized to obtain the
67 privileges of the target account.
68 If the target account is
69 .Dq root ,
70 then the Kerberos 5 principal used
71 for authentication and authorization will be the
72 .Dq root
73 instance of
74 the current user, e.g.\&
75 .Dq Li user/root@REAL.M .
76 Otherwise, the principal will simply be the current user's default
77 principal, e.g.\&
78 .Dq Li user@REAL.M .
79 .Pp
80 The user is prompted for a password if necessary.
81 Authorization is performed
82 by comparing the Kerberos 5 principal with those listed in the
83 .Pa .k5login
84 file in the target account's home directory
85 (e.g.\&
86 .Pa /root/.k5login
87 for root).
88 .Pp
89 The following options may be passed to the authentication module:
90 .Bl -tag -width ".Cm use_first_pass"
91 .It Cm debug
92 .Xr syslog 3
93 debugging information at
94 .Dv LOG_DEBUG
95 level.
96 .It Cm use_first_pass
97 If the authentication module
98 is not the first in the stack,
99 and a previous module
100 obtained the user's password,
101 that password is used
102 to authenticate the user.
103 If this fails,
104 the authentication module returns failure
105 without prompting the user for a password.
106 This option has no effect
107 if the authentication module
108 is the first in the stack,
109 or if no previous modules
110 obtained the user's password.
111 .It Cm try_first_pass
112 This option is similar to the
113 .Cm use_first_pass
114 option,
115 except that if the previously obtained password fails,
116 the user is prompted for another password.
117 .El
118 .Sh SEE ALSO
119 .Xr su 1 ,
120 .Xr syslog 3 ,
121 .Xr pam.conf 5 ,
122 .Xr pam 8