1.\" $NetBSD: pam_krb5.8,v 1.12 2017/07/03 21:32:51 wiz Exp $ 2.\" $FreeBSD: src/lib/libpam/modules/pam_krb5/pam_krb5.8,v 1.6 2001/11/24 23:41:32 dd Exp $ 3.\" 4.\" Copyright (c) Frank Cusack, 1999-2001. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notices, and the entire permission notice in its entirety, 11.\" including the disclaimer of warranties. 12.\" 2. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. The name of the author may not be used to endorse or promote 16.\" products derived from this software without specific prior 17.\" written permission. 18.\" 19.\" ALTERNATIVELY, this product may be distributed under the terms of 20.\" the GNU Public License, in which case the provisions of the GPL are 21.\" required INSTEAD OF the above restrictions. (This clause is 22.\" necessary due to a potential bad interaction between the GPL and 23.\" the restrictions contained in a BSD-style copyright.) 24.\" 25.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED 26.\" WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 27.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 28.\" DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, 29.\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 30.\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR 31.\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 32.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 33.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 35.\" OF THE POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd March 10, 2007 38.Dt PAM_KRB5 8 39.Os 40.Sh NAME 41.Nm pam_krb5 42.Nd Kerberos 5 PAM module 43.Sh SYNOPSIS 44.Op Ar service-name 45.Ar module-type 46.Ar control-flag 47.Pa pam_krb5 48.Op Ar arguments 49.Sh DESCRIPTION 50The Kerberos 5 service module for PAM 51provides functionality for three PAM categories: 52authentication, 53account management, 54and password management. 55It also provides null functions for session management. 56.Ss Kerberos 5 Authentication Module 57The Kerberos 5 authentication component 58provides functions to verify the identity of a user 59.Pq Fn pam_sm_authenticate 60and to set user specific credentials 61.Pq Fn pam_sm_setcred . 62.Fn pam_sm_authenticate 63converts the supplied username into a Kerberos principal, 64by appending the default local realm name. 65It also supports usernames with explicit realm names. 66If a realm name is supplied, then upon a successful return, it 67changes the username by mapping the principal name into a local username 68(calling 69.Fn krb5_aname_to_localname ) . 70This typically just means 71the realm name is stripped. 72.Pp 73It prompts the user for a password and obtains a new Kerberos TGT for 74the principal. 75The TGT is verified by obtaining a service 76ticket for the local host. 77.Pp 78When prompting for the current password, the authentication 79module will use the prompt 80.Dq Li "Password for <principal>:" . 81.Pp 82The 83.Fn pam_sm_setcred 84function stores the newly acquired credentials in a credentials cache, 85and sets the environment variable 86.Ev KRB5CCNAME 87appropriately. 88The credentials cache should be destroyed by the user at logout with 89.Xr kdestroy 1 . 90.Pp 91The following options may be passed to the authentication module: 92.Bl -tag -width ".Cm use_first_pass" 93.It Cm debug 94.Xr syslog 3 95debugging information at 96.Dv LOG_DEBUG 97level. 98.It Cm no_warn 99suppress warning messages to the user. 100These messages include 101reasons why the user's 102authentication attempt was declined. 103.It Cm use_first_pass 104If the authentication module is not the first in the stack, 105and a previous module obtained the user's password, that password is 106used to authenticate the user. 107If this fails, the authentication 108module returns failure without prompting the user for a password. 109This option has no effect if the authentication module is 110the first in the stack, or if no previous modules obtained the 111user's password. 112.It Cm try_first_pass 113This option is similar to the 114.Cm use_first_pass 115option, except that if the previously obtained password fails, the 116user is prompted for another password. 117.It Cm renewable Ns = Ns Ar timeperiod 118Obtain renewable Kerberos credentials for the user. 119The renewable time can be specified, or it defaults to one month. 120Since spaces are not allowed in the pam configuration time, underscores 121are used to form parseable times (e.g., 1_month). 122.It Cm forwardable 123Obtain forwardable Kerberos credentials for the user. 124.It Cm no_ccache 125Do not save the obtained credentials in a credentials cache. 126This is a 127useful option if the authentication module is used for services such 128as ftp or pop, where the user would not be able to destroy them. 129[This 130is not a recommendation to use the module for those services.] 131.It Cm ccache Ns = Ns Ar name 132Use 133.Ar name 134as the credentials cache. 135.Ar name 136must be in the form 137.Ar type : Ns Ar residual . 138The special tokens 139.Ql %u , 140to designate the decimal UID of the user; 141and 142.Ql %p , 143to designate the current process ID; can be used in 144.Ar name . 145.El 146.Ss Kerberos 5 Account Management Module 147The Kerberos 5 account management component 148provides a function to perform account management, 149.Fn pam_sm_acct_mgmt . 150The function verifies that the authenticated principal is allowed 151to login to the local user account by calling 152.Fn krb5_kuserok 153(which checks the user's 154.Pa .k5login 155file). 156.Ss Kerberos 5 Password Management Module 157The Kerberos 5 password management component 158provides a function to change passwords 159.Pq Fn pam_sm_chauthtok . 160The username supplied (the 161user running the 162.Xr passwd 1 163command, or the username given as an argument) is mapped into 164a Kerberos principal name, using the same technique as in 165the authentication module. 166Note that if a realm name was 167explicitly supplied during authentication, but not during 168a password change, the mapping 169done by the password management module may not result in the 170same principal as was used for authentication. 171.Pp 172Unlike when 173changing a 174.Ux 175password, the password management module will 176allow any user to change any principal's password (if the user knows 177the principal's old password, of course). 178Also unlike 179.Ux , 180root 181is always prompted for the principal's old password. 182.Pp 183The password management module uses the same heuristics as 184.Xr kpasswd 1 185to determine how to contact the Kerberos password server. 186.Pp 187The following options may be passed to the password management 188module: 189.Bl -tag -width ".Cm use_first_pass" 190.It Cm debug 191.Xr syslog 3 192debugging information at 193.Dv LOG_DEBUG 194level. 195.It Cm use_first_pass 196If the password management module is not the first in the stack, 197and a previous module obtained the user's old password, that password is 198used to authenticate the user. 199If this fails, the password 200management 201module returns failure without prompting the user for the old password. 202If successful, the new password entered to the previous module is also 203used as the new Kerberos password. 204If the new password fails, 205the password management module returns failure without 206prompting the user for a new password. 207.It Cm try_first_pass 208This option is similar to the 209.Cm use_first_pass 210option, except that if the previously obtained old or new passwords fail, 211the user is prompted for them. 212.El 213.Ss Kerberos 5 Session Management Module 214The Kerberos 5 session management component 215provides functions to initiate 216.Pq Fn pam_sm_open_session 217and terminate 218.Pq Fn pam_sm_close_session 219sessions. 220Since session management is not defined under Kerberos 5, 221both of these functions simply return success. 222They are provided 223only because of the naming conventions for PAM modules. 224.Sh ENVIRONMENT 225.Bl -tag -width "KRB5CCNAME" 226.It Ev KRB5CCNAME 227Location of the credentials cache. 228.El 229.Sh FILES 230.Bl -tag -width ".Pa /tmp/krb5cc_ Ns Ar uid" -compact 231.It Pa /tmp/krb5cc_ Ns Ar uid 232default credentials cache 233.Ar ( uid 234is the decimal UID of the user). 235.It Pa $HOME/.k5login 236file containing Kerberos principals that are allowed access. 237.El 238.Sh SEE ALSO 239.Xr kdestroy 1 , 240.Xr passwd 1 , 241.Xr syslog 3 , 242.Xr pam.conf 5 , 243.Xr pam 8 244.Sh NOTES 245Applications should not call 246.Fn pam_authenticate 247more than once between calls to 248.Fn pam_start 249and 250.Fn pam_end 251when using the Kerberos 5 PAM module. 252.Sh SECURITY CONSIDERATIONS 253The 254.Nm 255module implements what is fundamentally a password authentication scheme. 256It does not use a Kerberos 5 exchange between client and server, but rather 257authenticates the password provided by the client against the Kerberos KDC. 258Therefore, care should be taken to only use this module over a secure session 259.Po 260secure TTY, encrypted session, etc. 261.Pc , 262otherwise the user's Kerberos 5 password could be compromised. 263