diff --git a/ObsoleteFiles.inc b/ObsoleteFiles.inc --- a/ObsoleteFiles.inc +++ b/ObsoleteFiles.inc @@ -51,6 +51,9 @@ # xargs -n1 | sort | uniq -d; # done +# 20251121: Remove duplicate pam_krb5 manual page +OLD_FILES+=share/man/man8/pam-krb5.8.gz + # 20251112: Remove old MLINK to apmconf(8) OLD_FILES+=share/man/man8/apmconf.8.gz diff --git a/lib/libpam/modules/pam_krb5/Makefile b/lib/libpam/modules/pam_krb5/Makefile --- a/lib/libpam/modules/pam_krb5/Makefile +++ b/lib/libpam/modules/pam_krb5/Makefile @@ -30,6 +30,7 @@ .PATH: ${SRCDIR}/module \ ${SRCDIR}/portable \ ${SRCDIR}/pam-util \ + ${SRCDIR}/docs \ ${SRCDIR} PACKAGE= kerberos @@ -57,8 +58,8 @@ support.c \ vector.c -MANNODEV= pam-krb5.8 -MANNODEVLINKS= pam-krb5.8 pam_krb5.8 +MANNODEV= pam_krb5.8 +MANSRC.pam_krb5.8=pam-krb5.8 CFLAGS= -I${SRCDIR} \ -I${.CURDIR} \ @@ -74,6 +75,12 @@ module_options.c: .PHONY cp ${SRCDIR}/module/options.c module_options.c + +.if exists(pod2mdoc) +pam-krb5.8: pam_krb5.pod + sed -e 's/pam(7)/pam.conf(5)/' <${.ALLSRC} | \ + pod2mdoc -n pam_krb5 -s 8 >${.TARGET} +.endif .else PACKAGE= kerberos diff --git a/lib/libpam/modules/pam_krb5/pam-krb5.8 b/lib/libpam/modules/pam_krb5/pam-krb5.8 --- a/lib/libpam/modules/pam_krb5/pam-krb5.8 +++ b/lib/libpam/modules/pam_krb5/pam-krb5.8 @@ -1,1025 +1,1356 @@ -.\" -*- mode: troff; coding: utf-8 -*- -.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) -.\" -.\" Standard preamble: -.\" ======================================================================== -.de Sp \" Vertical space (when we can't use .PP) -.if t .sp .5v -.if n .sp -.. -.de Vb \" Begin verbatim text -.ft CW -.nf -.ne \\$1 -.. -.de Ve \" End verbatim text -.ft R -.fi -.. -.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. -.ie n \{\ -. ds C` "" -. ds C' "" -'br\} -.el\{\ -. ds C` -. ds C' -'br\} -.\" -.\" Escape single quotes in literal strings from groff's Unicode transform. -.ie \n(.g .ds Aq \(aq -.el .ds Aq ' -.\" -.\" If the F register is >0, we'll generate index entries on stderr for -.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index -.\" entries marked with X<> in POD. Of course, you'll have to process the -.\" output yourself in some meaningful fashion. -.\" -.\" Avoid warning from groff about undefined register 'F'. -.de IX -.. -.nr rF 0 -.if \n(.g .if rF .nr rF 1 -.if (\n(rF:(\n(.g==0)) \{\ -. if \nF \{\ -. de IX -. tm Index:\\$1\t\\n%\t"\\$2" -.. -. if !\nF==2 \{\ -. nr % 0 -. nr F 2 -. \} -. \} -.\} -.rr rF -.\" ======================================================================== -.\" -.IX Title "PAM_KRB5 1" -.TH PAM_KRB5 1 2025-06-05 "perl v5.40.2" "User Contributed Perl Documentation" -.\" For nroff, turn off justification. Always turn off hyphenation; it makes -.\" way too many mistakes in technical documents. -.if n .ad l -.nh -.SH NAME -pam_krb5 \- Kerberos PAM module -.SH SYNOPSIS -.IX Header "SYNOPSIS" -.Vb 4 -\& auth sufficient pam_krb5.so minimum_uid=1000 -\& session required pam_krb5.so minimum_uid=1000 -\& account required pam_krb5.so minimum_uid=1000 -\& password sufficient pam_krb5.so minimum_uid=1000 -.Ve -.SH DESCRIPTION -.IX Header "DESCRIPTION" +.Dd November 21, 2025 +.Dt PAM_KRB5 8 +.Os +.Sh NAME +.Nm pam_krb5 +.Nd Kerberos PAM module +.Sh SYNOPSIS +.Bd -literal + auth sufficient pam_krb5.so minimum_uid=1000 + session required pam_krb5.so minimum_uid=1000 + account required pam_krb5.so minimum_uid=1000 + password sufficient pam_krb5.so minimum_uid=1000 +.Ed +.Sh DESCRIPTION The Kerberos service module for PAM, typically installed at -\&\fI/lib/security/pam_krb5.so\fR, provides functionality for the four PAM -operations: authentication, account management, session management, and -password management. \fIpam_krb5.so\fR is a shared object that is -dynamically loaded by the PAM subsystem as necessary, based on the system -PAM configuration. PAM is a system for plugging in external -authentication and session management modules so that each application -doesn't have to know the best way to check user authentication or create a -user session on that system. For details on how to configure PAM on your -system, see the PAM man page, often \fBpam\fR\|(7). -.PP +.Pa /lib/security/pam_krb5.so , +provides functionality for the four PAM operations: authentication, +account management, session management, and password management. +.Pa pam_krb5.so +is a shared object that is dynamically loaded by the PAM subsystem as +necessary, based on the system PAM configuration. +PAM is a system for plugging in external authentication and session +management modules so that each application doesn't have to know the +best way to check user authentication or create a user session on that +system. +For details on how to configure PAM on your system, see the PAM man +page, often pam.conf(5). +.Pp Here are the actions of this module when called from each group: -.IP auth 4 -.IX Item "auth" -Provides implementations of \fBpam_authenticate()\fR and \fBpam_setcred()\fR. The -former takes the username from the PAM session, prompts for the user's -password (unless configured to use an already-entered password), and then -performs a Kerberos initial authentication, storing the obtained -credentials (if successful) in a temporary ticket cache. The latter, -depending on the flags it is called with, either takes the contents of the -temporary ticket cache and writes it out to a persistent ticket cache -owned by the user or uses the temporary ticket cache to refresh an -existing user ticket cache. -.Sp +.Bl -tag -width Ds +.It auth +Provides implementations of +.Xr pam_authenticate 3 +and +.Xr pam_setcred 3 . +The former takes the username from the PAM session, prompts for the +user's password (unless configured to use an already-entered password), +and then performs a Kerberos initial authentication, storing the +obtained credentials (if successful) in a temporary ticket cache. +The latter, depending on the flags it is called with, either takes the +contents of the temporary ticket cache and writes it out to a persistent +ticket cache owned by the user or uses the temporary ticket cache to +refresh an existing user ticket cache. +.Pp Passwords as long or longer than PAM_MAX_RESP_SIZE octets (normally 512 -octets) will be rejected, since excessively long passwords can be used as -a denial of service attack. -.Sp +octets) will be rejected, since excessively long passwords can be used +as a denial of service attack. +.Pp After doing the initial authentication, the Kerberos PAM module will attempt to obtain tickets for a key in the local system keytab and then -verify those tickets. Unless this step is performed, the authentication -is vulnerable to KDC spoofing, but it requires that the system have a -local key and that the PAM module be running as a user that can read the -keytab file (normally \fI/etc/krb5.keytab\fR. You can point the Kerberos PAM -module at a different keytab with the \fIkeytab\fR option. If that keytab -cannot be read or if no keys are found in it, the default (potentially -insecure) behavior is to skip this check. If you want to instead fail -authentication if the obtained tickets cannot be checked, set -\&\f(CW\*(C`verify_ap_req_nofail\*(C'\fR to true in the [libdefaults] section of -\&\fI/etc/krb5.conf\fR. Note that this will affect applications other than -this PAM module. -.Sp +verify those tickets. +Unless this step is performed, the authentication is vulnerable to KDC +spoofing, but it requires that the system have a local key and that the +PAM module be running as a user that can read the keytab file (normally +.Pa /etc/krb5.keytab . +You can point the Kerberos PAM module at a different keytab with the +.Em keytab +option. +If that keytab cannot be read or if no keys are found in it, the default +behavior is to fail authentication. +If you want to skip this check, set the +.Qo Li allow_kdc_spoof Qc +option to true either in the [appdefaults] section of +.Pa /etc/krb5.conf +or in the PAM policy. +.Pp By default, whenever the user is authenticated, a basic authorization -check will also be done using \fBkrb5_kuserok()\fR. The default behavior of -this function is to check the user's account for a \fI.k5login\fR file and, -if one is present, ensure that the user's principal is listed in that -file. If \fI.k5login\fR is not present, the default check is to ensure that -the user's principal is in the default local realm and the user portion of -the principal matches the account name (this can be changed by configuring -a custom aname to localname mapping in \fIkrb5.conf\fR; see the Kerberos -documentation for details). This can be customized with several -configuration options; see below. -.Sp -If the username provided to PAM contains an \f(CW\*(C`@\*(C'\fR and Kerberos can, -treating the username as a principal, map it to a local account name, -\&\fBpam_authenticate()\fR will change the PAM user to that local account name. -This allows users to log in with their Kerberos principal and let Kerberos -do the mapping to an account. This can be disabled with the -\&\fIno_update_user\fR option. Be aware, however, that this facility cannot be -used with OpenSSH. OpenSSH will reject usernames that don't match local -accounts before this remapping can be done and will pass an invalid -password to the PAM module. Also be aware that several other common PAM -modules, such as pam_securetty, expect to be able to look up the user with -\&\fBgetpwnam()\fR and cannot be called before pam_krb5 when using this feature. -.Sp -When \fBpam_setcred()\fR is called to initialize a new ticket cache, the -environment variable KRB5CCNAME is set to the path to that ticket cache. -By default, the cache will be named \fI/tmp/krb5cc_UID_RANDOM\fR where UID is -the user's UID and RANDOM is six randomly-chosen letters. This can be -configured with the \fIccache\fR and \fIccache_dir\fR options. -.Sp -pam\-krb5 does not use the default ticket cache location or -\&\fIdefault_cc_name\fR in the \f(CW\*(C`[libdefaults]\*(C'\fR section of \fIkrb5.conf\fR. The -default cache location would share a cache for all sessions of the same -user, which causes confusing behavior when the user logs out of one of -multiple sessions. -.Sp -If \fBpam_setcred()\fR initializes a new ticket cache, it will also set up that -ticket cache so that it will be deleted when the PAM session is closed. -Normally, the calling program (\fBlogin\fR, \fBsshd\fR, etc.) will run the -user's shell as a sub-process, wait for it to exit, and then close the PAM -session, thereby cleaning up the user's session. -.IP session 4 -.IX Item "session" -Provides implementations of \fBpam_open_session()\fR, which is equivalent to -calling \fBpam_setcred()\fR with the PAM_ESTABLISH_CRED flag, and -\&\fBpam_close_session()\fR, which destroys the ticket cache created by -\&\fBpam_setcred()\fR. -.IP account 4 -.IX Item "account" -Provides an implementation of \fBpam_acct_mgmt()\fR. All it does is do the same -authorization check as performed by the \fBpam_authenticate()\fR implementation -described above. -.IP password 4 -.IX Item "password" -Provides an implementation of \fBpam_chauthtok()\fR, which implements password -changes. The user is prompted for their existing password (unless -configured to use an already entered one) and the PAM module then obtains -credentials for the special Kerberos principal \f(CW\*(C`kadmin/changepw\*(C'\fR. It -then prompts the user for a new password, twice to ensure that the user -entered it properly (again, unless configured to use an already entered -password), and then does a Kerberos password change. -.Sp +check will also be done using +.Xr krb5_kuserok 3 . +The default behavior of this function is to check the user's account for +a +.Pa .k5login +file and, if one is present, ensure that the user's principal is listed +in that file. +If +.Pa .k5login +is not present, the default check is to ensure that the user's principal +is in the default local realm and the user portion of the principal +matches the account name (this can be changed by configuring a custom +aname to localname mapping in +.Pa krb5.conf ; +see the Kerberos documentation for details). +This can be customized with several configuration options; see below. +.Pp +If the username provided to PAM contains an +.Qo Li @ Qc +and Kerberos can, treating the username as a principal, map it to a +local account name, +.Xr pam_authenticate 3 +will change the PAM user to that local account name. +This allows users to log in with their Kerberos principal and let +Kerberos do the mapping to an account. +This can be disabled with the +.Em no_update_user +option. +Be aware, however, that this facility cannot be used with OpenSSH. +OpenSSH will reject usernames that don't match local accounts before +this remapping can be done and will pass an invalid password to the PAM +module. +Also be aware that several other common PAM modules, such as +pam_securetty, expect to be able to look up the user with +.Xr getpwnam 3 +and cannot be called before pam_krb5 when using this feature. +.Pp +When +.Xr pam_setcred 3 +is called to initialize a new ticket cache, the environment variable +KRB5CCNAME is set to the path to that ticket cache. +By default, the cache will be named +.Pa /tmp/krb5cc_UID_RANDOM +where UID is the user's UID and RANDOM is six randomly-chosen letters. +This can be configured with the +.Em ccache +and +.Em ccache_dir +options. +.Pp +pam-krb5 does not use the default ticket cache location or +.Em default_cc_name +in the +.Qo Li [libdefaults] Qc +section of +.Pa krb5.conf . +The default cache location would share a cache for all sessions of the +same user, which causes confusing behavior when the user logs out of one +of multiple sessions. +.Pp +If +.Xr pam_setcred 3 +initializes a new ticket cache, it will also set up that ticket cache so +that it will be deleted when the PAM session is closed. +Normally, the calling program +.Pf ( Sy login , +.Sy sshd , +etc.) +will run the user's shell as a sub-process, wait for it to exit, and +then close the PAM session, thereby cleaning up the user's session. +.It session +Provides implementations of +.Xr pam_open_session 3 , +which is equivalent to calling +.Xr pam_setcred 3 +with the PAM_ESTABLISH_CRED flag, and +.Xr pam_close_session 3 , +which destroys the ticket cache created by +.Xr pam_setcred 3 . +.It account +Provides an implementation of +.Xr pam_acct_mgmt 3 . +All it does is do the same authorization check as performed by the +.Xr pam_authenticate 3 +implementation described above. +.It password +Provides an implementation of +.Xr pam_chauthtok 3 , +which implements password changes. +The user is prompted for their existing password (unless configured to +use an already entered one) and the PAM module then obtains credentials +for the special Kerberos principal +.Qo Li kadmin/changepw Qc . +It then prompts the user for a new password, twice to ensure that the +user entered it properly (again, unless configured to use an already +entered password), and then does a Kerberos password change. +.Pp Passwords as long or longer than PAM_MAX_RESP_SIZE octets (normally 512 -octets) will be rejected, since excessively long passwords can be used as -a denial of service attack. -.Sp -Unlike the normal Unix password module, this module will allow any user to -change any other user's password if they know the old password. Also, -unlike the normal Unix password module, root will always be prompted for -the old password, since root has no special status in Kerberos. (To -change passwords in Kerberos without knowing the old password, use -\&\fBkadmin\fR\|(8) instead.) -.PP +octets) will be rejected, since excessively long passwords can be used +as a denial of service attack. +.Pp +Unlike the normal Unix password module, this module will allow any user +to change any other user's password if they know the old password. +Also, unlike the normal Unix password module, root will always be +prompted for the old password, since root has no special status in +Kerberos. +(To change passwords in Kerberos without knowing the old password, use +kadmin(8) instead.) +.El +.Pp Both the account and session management calls of the Kerberos PAM module will return PAM_IGNORE if called in the context of a PAM session for a -user who did not authenticate with Kerberos (a return code of \f(CW\*(C`ignore\*(C'\fR in -the Linux PAM configuration language). -.PP +user who did not authenticate with Kerberos (a return code of +.Qo Li ignore Qc +in the Linux PAM configuration language). +.Pp Note that this module assumes the network is available in order to do a -Kerberos authentication. If the network is not available, some Kerberos -libraries have timeouts longer than the timeout imposed by the login -process. This means that using this module incautiously can make it -impossible to log on to console as root. For this reason, you should -always use the \fIignore_root\fR or \fIminimum_uid\fR options, list a local -authentication module such as \fBpam_unix\fR first with a control field of -\&\f(CW\*(C`sufficient\*(C'\fR so that the Kerberos PAM module will be skipped if local -password authentication was successful. -.PP -This is not the same PAM module as the Kerberos PAM module available from -Sourceforge, or the one included on Red Hat systems. It supports many of -the same options, has some additional options, and doesn't support some of -the options those modules do. -.SH CONFIGURATION -.IX Header "CONFIGURATION" -The Kerberos PAM module takes many options, not all of which are relevant -to every PAM group; options that are not relevant will be silently -ignored. Any of these options can be set in the PAM configuration as -arguments listed after \f(CW\*(C`pam_krb5.so\*(C'\fR. Some of the options can also be -set in the system \fIkrb5.conf\fR file; if this is possible, it will be noted -below in the option description. -.PP -To set a boolean option in the PAM configuration file, just give the name -of the option in the arguments. To set an option that takes an argument, -follow the option name with an equal sign (=) and the value, with no -separating whitespace. Whitespace in option arguments is not supported in -the PAM configuration. -.PP -To set an option for the PAM module in the system \fIkrb5.conf\fR file, put -that option in the \f(CW\*(C`[appdefaults]\*(C'\fR section. All options must be followed -by an equal sign (=) and a value, so for boolean options add \f(CW\*(C`= true\*(C'\fR. +Kerberos authentication. +If the network is not available, some Kerberos libraries have timeouts +longer than the timeout imposed by the login process. +This means that using this module incautiously can make it impossible to +log on to console as root. +For this reason, you should always use the +.Em ignore_root +or +.Em minimum_uid +options, list a local authentication module such as +.Sy pam_unix +first with a control field of +.Qo Li sufficient Qc +so that the Kerberos PAM module will be skipped if local password +authentication was successful. +.Pp +This is not the same PAM module as the Kerberos PAM module available +from Sourceforge, or the one included on Red Hat systems. +It supports many of the same options, has some additional options, and +doesn't support some of the options those modules do. +.Sh CONFIGURATION +The Kerberos PAM module takes many options, not all of which are +relevant to every PAM group; options that are not relevant will be +silently ignored. +Any of these options can be set in the PAM configuration as arguments +listed after +.Qo Li pam_krb5.so Qc . +Some of the options can also be set in the system +.Pa krb5.conf +file; if this is possible, it will be noted below in the option +description. +.Pp +To set a boolean option in the PAM configuration file, just give the +name of the option in the arguments. +To set an option that takes an argument, follow the option name with an +equal sign (=) and the value, with no separating whitespace. +Whitespace in option arguments is not supported in the PAM +configuration. +.Pp +To set an option for the PAM module in the system +.Pa krb5.conf +file, put that option in the +.Qo Li [appdefaults] Qc +section. +All options must be followed by an equal sign (=) and a value, so for +boolean options add +.Qo Li = true Qc . The Kerberos PAM module will look for options either at the top level of -the \f(CW\*(C`[appdefaults]\*(C'\fR section or in a subsection named \f(CW\*(C`pam\*(C'\fR, inside or -outside a section for the realm. For example, the following fragment of a -\&\fIkrb5.conf\fR file would set \fIforwardable\fR to true, \fIminimum_uid\fR to -1000, and set \fIignore_k5login\fR only if the realm is EXAMPLE.COM. -.PP -.Vb 8 -\& [appdefaults] -\& forwardable = true -\& pam = { -\& minimum_uid = 1000 -\& EXAMPLE.COM = { -\& ignore_k5login = true -\& } -\& } -.Ve -.PP -For more information on the syntax of \fIkrb5.conf\fR, see \fBkrb5.conf\fR\|(5). -Note that options that depend on the realm will be set only on the basis -of the default realm, either as configured in \fBkrb5.conf\fR\|(5) or as set by -the \fIrealm\fR option described below. If the user authenticates to an -account qualified with a realm, that realm will not be used when -determining which options will apply. -.PP -There is no difference to the PAM module whether options are specified at -the top level or in a \f(CW\*(C`pam\*(C'\fR section; the \f(CW\*(C`pam\*(C'\fR section is supported in -case there are options that should be set for the PAM module but not for -other applications. -.PP -If the same option is set in \fIkrb5.conf\fR and in the PAM configuration, -the latter takes precedent. Note, however, that due to the configuration -syntax, there's no way to turn off a boolean option in the PAM -configuration that was turned on in \fIkrb5.conf\fR. -.PP +the +.Qo Li [appdefaults] Qc +section or in a subsection named +.Qo Li pam Qc , +inside or outside a section for the realm. +For example, the following fragment of a +.Pa krb5.conf +file would set +.Em forwardable +to true, +.Em minimum_uid +to 1000, and set +.Em ignore_k5login +only if the realm is EXAMPLE.COM. +.Bd -literal + [appdefaults] + forwardable = true + pam = { + minimum_uid = 1000 + EXAMPLE.COM = { + ignore_k5login = true + } + } +.Ed +.Pp +For more information on the syntax of +.Pa krb5.conf , +see krb5.conf(5). Note that options that depend on the realm will be set +only on the basis of the default realm, either as configured in +krb5.conf(5) or as set by the +.Em realm +option described below. +If the user authenticates to an account qualified with a realm, that +realm will not be used when determining which options will apply. +.Pp +There is no difference to the PAM module whether options are specified +at the top level or in a +.Qo Li pam Qc +section; the +.Qo Li pam Qc +section is supported in case there are options that should be set for +the PAM module but not for other applications. +.Pp +If the same option is set in +.Pa krb5.conf +and in the PAM configuration, the latter takes precedent. +Note, however, that due to the configuration syntax, there's no way to +turn off a boolean option in the PAM configuration that was turned on in +.Pa krb5.conf . +.Pp The start of each option description is annotated with the version of -pam\-krb5 in which that option was added with the current meaning. -.SS Authorization -.IX Subsection "Authorization" -.IP alt_auth_map= 4 -.IX Item "alt_auth_map=" -[3.12] This functions similarly to the \fIsearch_k5login\fR option. The - argument is used as the authentication Kerberos principal, with -any \f(CW%s\fR in replaced with the username. If the username -contains an \f(CW\*(C`@\*(C'\fR, only the part of the username before the realm is used -to replace \f(CW%s\fR. If contains a realm, it will be used; -otherwise, the realm of the username (if any) will be appended to the -result. There is no quote removal. -.Sp +pam-krb5 in which that option was added with the current meaning. +.Ss Authorization +.Bl -tag -width Ds +.It allow_kdc_spoof +Allow authentication to succeed even if there is no host or service key +available in a keytab to authenticate the Kerberos KDC's ticket. +.It alt_auth_map= +[3.12] This functions similarly to the +.Em search_k5login +option. +The argument is used as the authentication Kerberos principal, +with any +.Qo Li %s Qc +in replaced with the username. +If the username contains an +.Qo Li @ Qc , +only the part of the username before the realm is used to replace +.Qo Li %s Qc . +If contains a realm, it will be used; otherwise, the realm of +the username (if any) will be appended to the result. +There is no quote removal. +.Pp If this option is present, the default behavior is to try this alternate principal first and then fall back to the standard behavior if it fails. The primary usage is to allow alternative principals to be used for -authentication in programs like \fBsudo\fR. Most examples will look like: -.Sp -.Vb 1 -\& alt_auth_map=%s/root -.Ve -.Sp +authentication in programs like +.Sy sudo . +Most examples will look like: +.Bd -literal + alt_auth_map=%s/root +.Ed +.Pp which attempts authentication as the root instance of the username first -and then falls back to the regular username (but see \fIforce_alt_auth\fR and -\&\fIonly_alt_auth\fR). -.Sp +and then falls back to the regular username (but see +.Em force_alt_auth +and +.Em only_alt_auth Ns ). +.Pp This option also allows a cheap way to attempt authentication in an -alternative realm first and then fall back to the primary realm. A -setting like: -.Sp -.Vb 1 -\& alt_auth_map=%s@EXAMPLE.COM -.Ve -.Sp +alternative realm first and then fall back to the primary realm. +A setting like: +.Bd -literal + alt_auth_map=%s@EXAMPLE.COM +.Ed +.Pp will attempt authentication in the EXAMPLE.COM realm first and then fall -back on the local default realm. This is more convenient than running the -module multiple times with multiple default realms set with \fIrealm\fR, but -it is very limited: only two realms can be tried, and the alternate realm -is always tried first. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR, although -normally it doesn't make sense to do that; normally it is used in the PAM -options of configuration for specific programs. It is only applicable to -the auth and account groups. If this option is set for the auth group, be -sure to set it for the account group as well or account authorization may -fail. -.IP force_alt_auth 4 -.IX Item "force_alt_auth" -[3.12] This option is used with \fIalt_auth_map\fR and forces authentication -as the mapped principal if that principal exists in the KDC. Only if the -KDC returns principal unknown does the Kerberos PAM module fall back to -normal authentication. This can be used to force authentication with an -alternate instance. If \fIalt_auth_map\fR is not set, it has no effect. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP ignore_k5login 4 -.IX Item "ignore_k5login" -[2.0] Never look for a \fI.k5login\fR file in the user's home directory. -Instead, only check that the Kerberos principal maps to the local account -name. The default check is to ensure the realm matches the local realm -and the user portion of the principal matches the local account name, but -this can be customized by setting up an aname to localname mapping in -\&\fIkrb5.conf\fR. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth and account groups. -.IP ignore_root 4 -.IX Item "ignore_root" -[1.1] Do not do anything if the username is \f(CW\*(C`root\*(C'\fR. The authentication -and password calls will silently fail (allowing that status to be ignored -via a control of \f(CW\*(C`optional\*(C'\fR or \f(CW\*(C`sufficient\*(C'\fR), and the account and -session calls (including pam_setcred) will return PAM_IGNORE, telling the -PAM library to proceed as if they weren't mentioned in the PAM -configuration. This option is supported and will remain, but normally you -want to use \fIminimum_uid\fR instead. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR. -.IP minimum_uid= 4 -.IX Item "minimum_uid=" -[2.0] Do not do anything if the authenticated account name corresponds to -a local account and that local account has a UID lower than . If +back on the local default realm. +This is more convenient than running the module multiple times with +multiple default realms set with +.Em realm , +but it is very limited: only two realms can be tried, and the alternate +realm is always tried first. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf , +although normally it doesn't make sense to do that; normally it is used +in the PAM options of configuration for specific programs. +It is only applicable to the auth and account groups. +If this option is set for the auth group, be sure to set it for the +account group as well or account authorization may fail. +.It force_alt_auth +[3.12] This option is used with +.Em alt_auth_map +and forces authentication as the mapped principal if that principal +exists in the KDC. Only if the KDC returns principal unknown does the +Kerberos PAM module fall back to normal authentication. +This can be used to force authentication with an alternate instance. +If +.Em alt_auth_map +is not set, it has no effect. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It ignore_k5login +[2.0] Never look for a +.Pa .k5login +file in the user's home directory. +Instead, only check that the Kerberos principal maps to the local +account name. +The default check is to ensure the realm matches the local realm and the +user portion of the principal matches the local account name, but this +can be customized by setting up an aname to localname mapping in +.Pa krb5.conf . +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth and account groups. +.It ignore_root +[1.1] Do not do anything if the username is +.Qo Li root Qc . +The authentication and password calls will silently fail (allowing that +status to be ignored via a control of +.Qo Li optional Qc +or +.Qo Li sufficient Qc Ns ), +and the account and session calls (including pam_setcred) will return +PAM_IGNORE, telling the PAM library to proceed as if they weren't +mentioned in the PAM configuration. +This option is supported and will remain, but normally you want to use +.Em minimum_uid +instead. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf . +.It minimum_uid= +[2.0] Do not do anything if the authenticated account name corresponds +to a local account and that local account has a UID lower than . If both of those conditions are true, the authentication and password calls will silently fail (allowing that status to be ignored via a control of -\&\f(CW\*(C`optional\*(C'\fR or \f(CW\*(C`sufficient\*(C'\fR), and the account and session calls -(including pam_setcred) will return PAM_IGNORE, telling the PAM library to -proceed as if they weren't mentioned in the PAM configuration. -.Sp -Using this option is highly recommended if you don't need to use Kerberos -to authenticate password logins to the root account (which isn't -recommended since Kerberos requires a network connection). It provides -some defense in depth against user principals that happen to match a -system account incorrectly authenticating as that system account. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR. -.IP only_alt_auth 4 -.IX Item "only_alt_auth" -[3.12] This option is used with \fIalt_auth_map\fR and forces the use of the -mapped principal for authentication. It disables fallback to normal -authentication in all cases and overrides \fIsearch_k5login\fR and -\&\fIforce_alt_auth\fR. If \fIalt_auth_map\fR is not set, it has no effect and -the standard authentication behavior is used. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP search_k5login 4 -.IX Item "search_k5login" +.Qo Li optional Qc +or +.Qo Li sufficient Qc Ns ), +and the account and session calls (including pam_setcred) will return +PAM_IGNORE, telling the PAM library to proceed as if they weren't +mentioned in the PAM configuration. +.Pp +Using this option is highly recommended if you don't need to use +Kerberos to authenticate password logins to the root account (which +isn't recommended since Kerberos requires a network connection). +It provides some defense in depth against user principals that happen to +match a system account incorrectly authenticating as that system +account. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf . +.It only_alt_auth +[3.12] This option is used with +.Em alt_auth_map +and forces the use of the mapped principal for authentication. +It disables fallback to normal authentication in all cases and overrides +.Em search_k5login +and +.Em force_alt_auth . +If +.Em alt_auth_map +is not set, it has no effect and the standard authentication behavior is +used. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It search_k5login [2.0] Normally, the Kerberos implementation of pam_authenticate attempts -to obtain tickets for the authenticating username in the local realm. If -this option is set and the local user has a \fI.k5login\fR file in their home -directory, the module will instead open and read that \fI.k5login\fR file, -attempting to use the supplied password to authenticate as each principal -listed there in turn. If any of those authentications succeed, the user -will be successfully authenticated; otherwise, authentication will fail. -This option is useful for allowing password authentication (via console or -\&\fBsshd\fR without GSS-API support) to shared accounts. If there is no -\&\fI.k5login\fR file, the behavior is the same as normal. Using this option -requires that the user's \fI.k5login\fR file be readable at the time of -authentication. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.SS "Kerberos Behavior" -.IX Subsection "Kerberos Behavior" -.IP anon_fast 4 -.IX Item "anon_fast" +to obtain tickets for the authenticating username in the local realm. +If this option is set and the local user has a +.Pa .k5login +file in their home directory, the module will instead open and read that +.Pa .k5login +file, attempting to use the supplied password to authenticate as each +principal listed there in turn. +If any of those authentications succeed, the user will be successfully +authenticated; otherwise, authentication will fail. +This option is useful for allowing password authentication (via console +or +.Sy sshd +without GSS-API support) to shared accounts. +If there is no +.Pa .k5login +file, the behavior is the same as normal. +Using this option requires that the user's +.Pa .k5login +file be readable at the time of authentication. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.El +.Ss Kerberos Behavior +.Bl -tag -width Ds +.It anon_fast [4.6] Attempt to use Flexible Authentication Secure Tunneling (FAST) by -first authenticating as the anonymous user (WELLKNOWN/ANONYMOUS) and using -its credentials as the FAST armor. This requires anonymous PKINIT be -enabled for the local realm, that PKINIT be configured on the local -system, and that the Kerberos library support FAST and anonymous PKINIT. -.Sp -FAST is a mechanism to protect Kerberos against password guessing attacks -and provide other security improvements. To work, FAST requires that a -ticket be obtained with a strong key to protect exchanges with potentially -weaker user passwords. This option uses anonymous authentication to -obtain that key and then uses it to protect the subsequent authentication. -.Sp +first authenticating as the anonymous user (WELLKNOWN/ANONYMOUS) and +using its credentials as the FAST armor. +This requires anonymous PKINIT be enabled for the local realm, that +PKINIT be configured on the local system, and that the Kerberos library +support FAST and anonymous PKINIT. +.Pp +FAST is a mechanism to protect Kerberos against password guessing +attacks and provide other security improvements. +To work, FAST requires that a ticket be obtained with a strong key to +protect exchanges with potentially weaker user passwords. +This option uses anonymous authentication to obtain that key and then +uses it to protect the subsequent authentication. +.Pp If anonymous PKINIT is not available or fails, FAST will not be used and the authentication will proceed as normal. -.Sp +.Pp To instead use an existing ticket cache for the FAST credentials, use -\&\fIfast_ccache\fR instead of this option. If both \fIfast_ccache\fR and -\&\fIanon_fast\fR are set, the ticket cache named by \fIfast_ccache\fR will be -tried first, and the Kerberos PAM module will fall back on attempting -anonymous PKINIT if that cache could not be used. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth and password groups. -.Sp -The operation is the same as if using the \fIfast_ccache\fR option, but the -cache is created and destroyed automatically. If both \fIfast_ccache\fR and -\&\fIanon_fast\fR options are used, the \fIfast_ccache\fR takes precedent and no -anonymous authentication is done. -.IP fast_ccache= 4 -.IX Item "fast_ccache=" -[4.3] The same as \fIanon_fast\fR, but use an existing Kerberos ticket cache -rather than anonymous PKINIT. This allows use of FAST with a realm that -doesn't support PKINIT or doesn't support anonymous authentication. -.Sp +.Em fast_ccache +instead of this option. +If both +.Em fast_ccache +and +.Em anon_fast +are set, the ticket cache named by +.Em fast_ccache +will be tried first, and the Kerberos PAM module will fall back on +attempting anonymous PKINIT if that cache could not be used. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth and password groups. +.Pp +The operation is the same as if using the +.Em fast_ccache +option, but the cache is created and destroyed automatically. +If both +.Em fast_ccache +and +.Em anon_fast +options are used, the +.Em fast_ccache +takes precedent and no anonymous authentication is done. +.It fast_ccache= +[4.3] The same as +.Em anon_fast , +but use an existing Kerberos ticket cache rather than anonymous PKINIT. +This allows use of FAST with a realm that doesn't support PKINIT or +doesn't support anonymous authentication. +.Pp should be a credential cache containing a ticket obtained using a strong key, such as the randomized key for the host principal of -the local system. If names a ticket cache that is readable -by the authenticating process and has tickets then FAST will be attempted. -The easiest way to use this option is to use a program like \fBk5start\fR to -maintain a ticket cache using the host's keytab. This ticket cache should -normally only be readable by root, so this option will not be able to -protect authentications done as non-root users (such as screensavers). -.Sp -If no credentials are present in the ticket cache, or if the ticket cache -does not exist or is not readable, FAST will not used and authentication -will proceed as normal. However, if the credentials in that ticket cache -are expired, authentication will fail if the KDC supports FAST. -.Sp -To use anonymous PKINIT to protect the FAST exchange, use the \fIanon_fast\fR -option instead. \fIanon_fast\fR is easier to configure, since no existing -ticket cache is required, but requires PKINIT be available and configured -and that the local realm support anonymous authentication. If both -\&\fIfast_ccache\fR and \fIanon_fast\fR are set, the ticket cache named by -\&\fIfast_ccache\fR will be tried first, and the Kerberos PAM module will fall -back on attempting anonymous PKINIT if that cache could not be used. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth and password groups. -.IP forwardable 4 -.IX Item "forwardable" -[1.0] Obtain forwardable tickets. If set (to either true or false, -although it can only be set to false in \fIkrb5.conf\fR), this overrides the -Kerberos library default set in the [libdefaults] section of \fIkrb5.conf\fR. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP keytab= 4 -.IX Item "keytab=" -[3.0] Specifies the keytab to use when validating the user's credentials. -The default is the default system keytab (normally \fI/etc/krb5.keytab\fR), -which is usually only readable by root. Applications not running as root -that use this PAM module for authentication may wish to point it to -another keytab the application can read. The first principal found in the -keytab will be used as the principal for credential verification. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP realm= 4 -.IX Item "realm=" -[2.2] Set the default Kerberos realm and obtain credentials in that realm, -rather than in the normal default realm for this system. If this option -is used, it should be set for all groups being used for consistent -results. This setting will affect authorization decisions since it -changes the default realm. This setting will also change the service -principal used to verify the obtained credentials to be in the specified -realm. -.Sp +the local system. +If names a ticket cache that is readable by the +authenticating process and has tickets then FAST will be attempted. +The easiest way to use this option is to use a program like +.Sy k5start +to maintain a ticket cache using the host's keytab. +This ticket cache should normally only be readable by root, so this +option will not be able to protect authentications done as non-root +users (such as screensavers). +.Pp +If no credentials are present in the ticket cache, or if the ticket +cache does not exist or is not readable, FAST will not used and +authentication will proceed as normal. +However, if the credentials in that ticket cache are expired, +authentication will fail if the KDC supports FAST. +.Pp +To use anonymous PKINIT to protect the FAST exchange, use the +.Em anon_fast +option instead. +.Em anon_fast +is easier to configure, since no existing ticket cache is required, but +requires PKINIT be available and configured and that the local realm +support anonymous authentication. +If both +.Em fast_ccache +and +.Em anon_fast +are set, the ticket cache named by +.Em fast_ccache +will be tried first, and the Kerberos PAM module will fall back on +attempting anonymous PKINIT if that cache could not be used. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth and password groups. +.It forwardable +[1.0] Obtain forwardable tickets. +If set (to either true or false, although it can only be set to false in +.Pa krb5.conf Ns ), +this overrides the Kerberos library default set in the [libdefaults] +section of +.Pa krb5.conf . +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It keytab= +[3.0] Specifies the keytab to use when validating the user's +credentials. +The default is the default system keytab (normally +.Pa /etc/krb5.keytab Ns ), +which is usually only readable by root. +Applications not running as root that use this PAM module for +authentication may wish to point it to another keytab the application +can read. +The first principal found in the keytab will be used as the principal +for credential verification. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It realm= +[2.2] Set the default Kerberos realm and obtain credentials in that +realm, rather than in the normal default realm for this system. +If this option is used, it should be set for all groups being used for +consistent results. +This setting will affect authorization decisions since it changes the +default realm. +This setting will also change the service principal used to verify the +obtained credentials to be in the specified realm. +.Pp If you only want to set the realm assumed for user principals without changing the realm for authorization decisions or the service principal -used to verify credentials, see the \fIuser_realm\fR option. -.IP renew_lifetime= 4 -.IX Item "renew_lifetime=" +used to verify credentials, see the +.Em user_realm +option. +.It renew_lifetime= [2.0] Obtain renewable tickets with a maximum renewable lifetime of -. should be a Kerberos lifetime string such as -\&\f(CW\*(C`2d4h10m\*(C'\fR or a time in minutes. If set, this overrides the Kerberos -library default set in the [libdefaults] section of \fIkrb5.conf\fR. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP ticket_lifetime= 4 -.IX Item "ticket_lifetime=" -[3.0] Obtain tickets with a maximum lifetime of . -should be a Kerberos lifetime string such as \f(CW\*(C`2d4h10m\*(C'\fR or a time in -minutes. If set, this overrides the Kerberos library default set in the -[libdefaults] section of \fIkrb5.conf\fR. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP user_realm 4 -.IX Item "user_realm" -[4.6] Obtain credentials in the specified realm rather than in the default -realm for this system. If this option is used, it should be set for all -groups being used for consistent results (although the account group -currently doesn't care about realm). This will not change authorization -decisions. If the obtained credentials are supposed to allow access to a -shell account, the user will need an appropriate \fI.k5login\fR file entry or -the system will have to have a custom aname_to_localname mapping. -.SS "PAM Behavior" -.IX Subsection "PAM Behavior" -.IP clear_on_fail 4 -.IX Item "clear_on_fail" -[3.9] When changing passwords, PAM first does a preliminary check through -the complete password stack, and then calls each module again to do the -password change. After that preliminary check, the order of module -invocation is fixed. This means that even if the Kerberos password change -fails (or if one of the other password changes in the stack fails), other -password PAM modules in the stack will still be called even if the failing -module is marked required or requisite. When using multiple password PAM -modules to synchronize passwords between multiple systems when they -change, this behavior can cause unwanted differences between the -environments. -.Sp -Setting this option provides a way to work around this behavior. If this -option is set and a Kerberos password change is attempted and fails (due -to network errors or password strength checking on the KDC, for example), -this module will clear the stored password in the PAM stack. This will -force any subsequent modules that have \fIuse_authtok\fR set to fail so that -those environments won't get out of sync with the password in Kerberos. +. should be a Kerberos lifetime string such as +.Qo Li 2d4h10m Qc +or a time in minutes. +If set, this overrides the Kerberos library default set in the +[libdefaults] section of +.Pa krb5.conf . +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It ticket_lifetime= +[3.0] Obtain tickets with a maximum lifetime of . +should be a Kerberos lifetime string such as +.Qo Li 2d4h10m Qc +or a time in minutes. +If set, this overrides the Kerberos library default set in the +[libdefaults] section of +.Pa krb5.conf . +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It user_realm +[4.6] Obtain credentials in the specified realm rather than in the +default realm for this system. +If this option is used, it should be set for all groups being used for +consistent results (although the account group currently doesn't care +about realm). +This will not change authorization decisions. +If the obtained credentials are supposed to allow access to a shell +account, the user will need an appropriate +.Pa .k5login +file entry or the system will have to have a custom aname_to_localname +mapping. +.El +.Ss PAM Behavior +.Bl -tag -width Ds +.It clear_on_fail +[3.9] When changing passwords, PAM first does a preliminary check +through the complete password stack, and then calls each module again to +do the password change. +After that preliminary check, the order of module invocation is fixed. +This means that even if the Kerberos password change fails (or if one of +the other password changes in the stack fails), other password PAM +modules in the stack will still be called even if the failing module is +marked required or requisite. +When using multiple password PAM modules to synchronize passwords +between multiple systems when they change, this behavior can cause +unwanted differences between the environments. +.Pp +Setting this option provides a way to work around this behavior. +If this option is set and a Kerberos password change is attempted and +fails (due to network errors or password strength checking on the KDC, +for example), this module will clear the stored password in the PAM +stack. +This will force any subsequent modules that have +.Em use_authtok +set to fail so that those environments won't get out of sync with the +password in Kerberos. The Kerberos PAM module will not meddle with the stored password if it skips the user due to configuration such as minimum_uid. -.Sp +.Pp Unfortunately, setting this option interferes with other desirable PAM configurations, such as attempting to change the password in Kerberos -first and falling back on the local Unix password database if that fails. -It therefore isn't the default. Turn it on (and list pam_krb5 first after -pam_cracklib if used) when synchronizing passwords between multiple -environments. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the password group. -.IP debug 4 -.IX Item "debug" +first and falling back on the local Unix password database if that +fails. +It therefore isn't the default. +Turn it on (and list pam_krb5 first after pam_cracklib if used) when +synchronizing passwords between multiple environments. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the password group. +.It debug [1.0] Log more verbose trace and debugging information to syslog at -LOG_DEBUG priority, including entry and exit from each of the external PAM -interfaces (except pam_close_session). -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR. -.IP defer_pwchange 4 -.IX Item "defer_pwchange" -[3.11] By default, pam\-krb5 lets the Kerberos library handle prompting for -a password change if an account's password is expired during the auth -group. If this fails, \fBpam_authenticate()\fR returns an error. -.Sp +LOG_DEBUG priority, including entry and exit from each of the external +PAM interfaces (except pam_close_session). +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf . +.It defer_pwchange +[3.11] By default, pam-krb5 lets the Kerberos library handle prompting +for a password change if an account's password is expired during the +auth group. +If this fails, +.Xr pam_authenticate 3 +returns an error. +.Pp According to the PAM standard, this is not the correct way to handle -expired passwords. Instead, \fBpam_authenticate()\fR should return success -without attempting a password change, and then \fBpam_acct_mgmt()\fR should -return PAM_NEW_AUTHTOK_REQD, at which point the calling application is -responsible for either rejecting the authentication or calling -\&\fBpam_chauthtok()\fR. However, following the standard requires that all -applications call \fBpam_acct_mgmt()\fR and check its return status; otherwise, -expired accounts may be able to successfully authenticate. Many -applications do not do this. -.Sp -If this option is set, pam\-krb5 uses the fully correct PAM mechanism for -handling expired accounts instead of failing in \fBpam_authenticate()\fR. Due -to the security risk of widespread broken applications, be very careful -about enabling this option. It should normally only be turned on to solve -a specific problem (such as using Solaris Kerberos libraries that don't -support prompting for password changes during authentication), and then -only for specific applications known to call \fBpam_acct_mgmt()\fR and check its -return status properly. -.Sp -This option is only supported when pam\-krb5 is built with MIT Kerberos. +expired passwords. +Instead, +.Xr pam_authenticate 3 +should return success without attempting a password change, and then +.Xr pam_acct_mgmt 3 +should return PAM_NEW_AUTHTOK_REQD, at which point the calling +application is responsible for either rejecting the authentication or +calling +.Xr pam_chauthtok 3 . +However, following the standard requires that all applications call +.Xr pam_acct_mgmt 3 +and check its return status; otherwise, expired accounts may be able to +successfully authenticate. +Many applications do not do this. +.Pp +If this option is set, pam-krb5 uses the fully correct PAM mechanism for +handling expired accounts instead of failing in +.Xr pam_authenticate 3 . +Due to the security risk of widespread broken applications, be very +careful about enabling this option. +It should normally only be turned on to solve a specific problem (such +as using Solaris Kerberos libraries that don't support prompting for +password changes during authentication), and then only for specific +applications known to call +.Xr pam_acct_mgmt 3 +and check its return status properly. +.Pp +This option is only supported when pam-krb5 is built with MIT Kerberos. If built against Heimdal, this option does nothing and normal expired -password change handling still happens. (Heimdal is missing the required -API to implement this option, at least as of version 1.6.) -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP fail_pwchange 4 -.IX Item "fail_pwchange" -[4.2] By default, pam\-krb5 lets the Kerberos library handle prompting for -a password change if an account's password is expired during the auth -group. If this option is set, expired passwords are instead treated as an -authentication failure identical to an incorrect password. Also see -\&\fIdefer_pwchange\fR and \fIforce_pwchange\fR. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP force_pwchange 4 -.IX Item "force_pwchange" +password change handling still happens. +(Heimdal is missing the required API to implement this option, at least +as of version 1.6.) +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It fail_pwchange +[4.2] By default, pam-krb5 lets the Kerberos library handle prompting +for a password change if an account's password is expired during the +auth group. +If this option is set, expired passwords are instead treated as an +authentication failure identical to an incorrect password. +Also see +.Em defer_pwchange +and +.Em force_pwchange . +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It force_pwchange [3.11] If this option is set and authentication fails with a Kerberos error indicating the user's password is expired, attempt to immediately -change their password during the authenticate step. Under normal -circumstances, this is unnecessary. Most Kerberos libraries will do this -for you, and setting this option will prompt the user twice to change -their password if the first attempt (done by the Kerberos library) fails. -However, some system Kerberos libraries (such as Solaris's) have password -change prompting disabled in the Kerberos library; on those systems, you -can set this option to simulate the normal library behavior. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP no_update_user 4 -.IX Item "no_update_user" -[4.7] Normally, if pam\-krb5 is able to canonicalize the principal to a -local name using \fBkrb5_aname_to_localname()\fR or similar calls, it changes -the PAM_USER variable for this PAM session to the canonicalized local -name. Setting this option disables this behavior and leaves PAM_USER set -to the initial authentication identity. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth group. -.IP silent 4 -.IX Item "silent" +change their password during the authenticate step. +Under normal circumstances, this is unnecessary. +Most Kerberos libraries will do this for you, and setting this option +will prompt the user twice to change their password if the first attempt +(done by the Kerberos library) fails. +However, some system Kerberos libraries (such as Solaris's) have +password change prompting disabled in the Kerberos library; on those +systems, you can set this option to simulate the normal library +behavior. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It no_update_user +[4.7] Normally, if pam-krb5 is able to canonicalize the principal to a +local name using +.Xr krb5_aname_to_localname 3 +or similar calls, it changes the PAM_USER variable for this PAM session +to the canonicalized local name. +Setting this option disables this behavior and leaves PAM_USER set to +the initial authentication identity. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth group. +.It silent [1.0] Don't show messages and errors from Kerberos, such as warnings of -expiring passwords, to the user via the prompter. This is equivalent to -the behavior when the application passes in PAM_SILENT, but can be set in -the PAM configuration. -.Sp +expiring passwords, to the user via the prompter. +This is equivalent to the behavior when the application passes in +PAM_SILENT, but can be set in the PAM configuration. +.Pp This option is only applicable to the auth and password groups. -.IP trace= 4 -.IX Item "trace=" -[4.6] Enables Kerberos library trace logging to the specified log file if -it is supported by the Kerberos library. This is intended for temporary -debugging. The specified file will be appended to without further -security checks, so do not specify a file in a publicly writable directory -like \fI/tmp\fR. -.SS PKINIT -.IX Subsection "PKINIT" -.IP pkinit_anchors= 4 -.IX Item "pkinit_anchors=" -[3.0] When doing PKINIT authentication, use as the client trust -anchors. This is normally a reference to a file containing the trusted -certificate authorities. This option is only used if \fItry_pkinit\fR or -\&\fIuse_pkinit\fR are set. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth and password groups. -.IP pkinit_prompt 4 -.IX Item "pkinit_prompt" -[3.0] Before attempting PKINIT authentication, prompt the user to insert a -smart card. You may want to set this option for programs such as -\&\fBgnome-screensaver\fR that call PAM as soon as the mouse is touched and -don't give the user an opportunity to enter the smart card first. Any -information entered at the first prompt is ignored. If \fItry_pkinit\fR is -set, a user who wishes to use a password instead can just press Enter and -then enter their password as normal. This option is only used if -\&\fItry_pkinit\fR or \fIuse_pkinit\fR are set. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth and password groups. -.IP pkinit_user= 4 -.IX Item "pkinit_user=" -[3.0] When doing PKINIT authentication, use as the user ID. The +.It trace= +[4.6] Enables Kerberos library trace logging to the specified log file +if it is supported by the Kerberos library. +This is intended for temporary debugging. +The specified file will be appended to without further security checks, +so do not specify a file in a publicly writable directory like +.Pa /tmp . +.El +.Ss PKINIT +.Bl -tag -width Ds +.It pkinit_anchors= +[3.0] When doing PKINIT authentication, use as the client +trust anchors. +This is normally a reference to a file containing the trusted +certificate authorities. +This option is only used if +.Em try_pkinit +or +.Em use_pkinit +are set. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth and password groups. +.It pkinit_prompt +[3.0] Before attempting PKINIT authentication, prompt the user to insert +a smart card. +You may want to set this option for programs such as +.Sy gnome-screensaver +that call PAM as soon as the mouse is touched and don't give the user an +opportunity to enter the smart card first. +Any information entered at the first prompt is ignored. +If +.Em try_pkinit +is set, a user who wishes to use a password instead can just press Enter +and then enter their password as normal. +This option is only used if +.Em try_pkinit +or +.Em use_pkinit +are set. +.Pp +This option can be set in +.Qo Li [appdefaults] Qc +in +.Pa krb5.conf +and is only applicable to the auth and password groups. +.It pkinit_user= +[3.0] When doing PKINIT authentication, use as the user ID. The value of this string is highly dependent on the type of PKINIT implementation you're using, but will generally be something like: -.Sp -.Vb 1 -\& PKCS11:/usr/lib/pkcs11/lib/soft\-pkcs11.so -.Ve -.Sp -to specify the module to use with a smart card. It may also point to a -user certificate or to other types of user IDs. See the Kerberos library -documentation for more details. This option is only used if \fItry_pkinit\fR -or \fIuse_pkinit\fR are set. -.Sp -This option can be set in \f(CW\*(C`[appdefaults]\*(C'\fR in \fIkrb5.conf\fR and is only -applicable to the auth and password groups. -.IP preauth_opt=