1.\" $NetBSD: pam_krb5.8,v 1.13 2023/06/20 22:17:18 riastradh 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.It Cm allow_kdc_spoof 146Allow 147.Nm 148to succeed even if there is no host or service key available in a 149keytab to authenticate the Kerberos KDC's ticket. 150If there is no such key, for example on a host with no keytabs, 151.Nm 152will fail immediately without prompting the user. 153.Pp 154.Sy Warning : 155If the host has not been configured with a keytab from the KDC, setting 156this option makes it vulnerable to malicious KDCs, e.g. via DNS 157flooding, because 158.Nm 159has no way to distinguish the legitimate KDC from a spoofed KDC. 160.El 161.Ss Kerberos 5 Account Management Module 162The Kerberos 5 account management component 163provides a function to perform account management, 164.Fn pam_sm_acct_mgmt . 165The function verifies that the authenticated principal is allowed 166to login to the local user account by calling 167.Fn krb5_kuserok 168(which checks the user's 169.Pa .k5login 170file). 171.Ss Kerberos 5 Password Management Module 172The Kerberos 5 password management component 173provides a function to change passwords 174.Pq Fn pam_sm_chauthtok . 175The username supplied (the 176user running the 177.Xr passwd 1 178command, or the username given as an argument) is mapped into 179a Kerberos principal name, using the same technique as in 180the authentication module. 181Note that if a realm name was 182explicitly supplied during authentication, but not during 183a password change, the mapping 184done by the password management module may not result in the 185same principal as was used for authentication. 186.Pp 187Unlike when 188changing a 189.Ux 190password, the password management module will 191allow any user to change any principal's password (if the user knows 192the principal's old password, of course). 193Also unlike 194.Ux , 195root 196is always prompted for the principal's old password. 197.Pp 198The password management module uses the same heuristics as 199.Xr kpasswd 1 200to determine how to contact the Kerberos password server. 201.Pp 202The following options may be passed to the password management 203module: 204.Bl -tag -width ".Cm use_first_pass" 205.It Cm debug 206.Xr syslog 3 207debugging information at 208.Dv LOG_DEBUG 209level. 210.It Cm use_first_pass 211If the password management module is not the first in the stack, 212and a previous module obtained the user's old password, that password is 213used to authenticate the user. 214If this fails, the password 215management 216module returns failure without prompting the user for the old password. 217If successful, the new password entered to the previous module is also 218used as the new Kerberos password. 219If the new password fails, 220the password management module returns failure without 221prompting the user for a new password. 222.It Cm try_first_pass 223This option is similar to the 224.Cm use_first_pass 225option, except that if the previously obtained old or new passwords fail, 226the user is prompted for them. 227.El 228.Ss Kerberos 5 Session Management Module 229The Kerberos 5 session management component 230provides functions to initiate 231.Pq Fn pam_sm_open_session 232and terminate 233.Pq Fn pam_sm_close_session 234sessions. 235Since session management is not defined under Kerberos 5, 236both of these functions simply return success. 237They are provided 238only because of the naming conventions for PAM modules. 239.Sh ENVIRONMENT 240.Bl -tag -width "KRB5CCNAME" 241.It Ev KRB5CCNAME 242Location of the credentials cache. 243.El 244.Sh FILES 245.Bl -tag -width ".Pa /tmp/krb5cc_ Ns Ar uid" -compact 246.It Pa /tmp/krb5cc_ Ns Ar uid 247default credentials cache 248.Ar ( uid 249is the decimal UID of the user). 250.It Pa $HOME/.k5login 251file containing Kerberos principals that are allowed access. 252.El 253.Sh SEE ALSO 254.Xr kdestroy 1 , 255.Xr passwd 1 , 256.Xr syslog 3 , 257.Xr pam.conf 5 , 258.Xr pam 8 259.Sh NOTES 260Applications should not call 261.Fn pam_authenticate 262more than once between calls to 263.Fn pam_start 264and 265.Fn pam_end 266when using the Kerberos 5 PAM module. 267.Sh SECURITY CONSIDERATIONS 268The 269.Nm 270module implements what is fundamentally a password authentication scheme. 271It does not use a Kerberos 5 exchange between client and server, but rather 272authenticates the password provided by the client against the Kerberos KDC. 273Therefore, care should be taken to only use this module over a secure session 274.Po 275secure TTY, encrypted session, etc. 276.Pc , 277otherwise the user's Kerberos 5 password could be compromised. 278