From nobody Tue Jun 17 20:26:47 2025 X-Original-To: dev-commits-src-main@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bMJLb43bnz5pk7L; Tue, 17 Jun 2025 20:26:47 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R11" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bMJLb2x7jz3n06; Tue, 17 Jun 2025 20:26:47 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1750192007; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=8NQqQBvycjcrmqnNOZjaumdYJh4QnzFaruDQImgskUY=; b=RZr56K37AkHOh1HcOcvnOL+M2x0CGep5ZzwWI8APvlpLw9cp8kPEaoYDFAS4BGseIq8v/6 cDYbRUwcxEx4gebLNp8ACa2CEU4YJxaFZR2LdZ/COxiPV9NcKDoBf3wpoTskTQ+1vWcikT epHxqsXtiy4DQRoRXCPl/M6YSlj447tiNAF8PboN9oxvhlhd2uHRxSEpvkh/5SOng1NxKO Tmv6KTIejzvFOQ/p8dtoTEXVqZ0o1dEbmbtENaqqWHCbZ0b1Ko/I0y8ZM+z3ShcAwQpch8 M8ezPtVSo8buf7m7Fqzli8j9Y0O7VhKRRpnr7PyeQJ3YDXa6JsROsI9TQrLdnA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1750192007; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=8NQqQBvycjcrmqnNOZjaumdYJh4QnzFaruDQImgskUY=; b=ulDmkBLyFKqggDbmpW2glNtHtQe6LftgvWhcH7qGaj4m8pt1Rd3z+88bFoh/cZsn7Wiwms QeB4/0z8JfcdxzQphxrp3ij0Cz3vjnYqbFbvMhRorsmCkhl8MaMUwdah5CdEuGp9Qi2lKA /M470CebYA8URp+c9ShP1fIRh4Otte2SlfuS95sCsQhgCjvqcvpYbxdTAPVrUkkrDPb/MM WqiyunNfcgyyAdYKfY6hwTx6XjwkXJrNAWmC6gcs1FY1CtuYaAhyUi1fsl3p31sq09FPW0 /mcFNYSrZf1HmxBOWj3fmc2rQtq8vSxvZMbQ7tiHo94uiTymbjOQdLSGA6N27w== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1750192007; a=rsa-sha256; cv=none; b=KkZyt3s1vWXec5ANMaX3NHj7/XIpqqqMERc5hjOs2Fx2LAg8vyqor8OS+HvN+er8VYE5+3 1ohD9vNrHbrRBeqiEcXOIgqBWon+QFiWDtDl+A1ZAlQwV9QiwZmE0HtdWb8SRp5YQEZphc s/YBpC1t4FWycXiuQ3aCNacXrPyvTm6WV4KZBcVEr3RItK48jmjqStpgtSbAlAmJGKdkFT DIyLgLCiDoUPfEZ33Xs6Q9QGfWLpArr5oRsdPbrlstKbrwMfxpXrPJEd4BnzPOeDD0yYX4 KdX920FyY+m0DYBxBKdyB+3lX17GrXiN8cO95EzuAri0/IWGXfcVm2DaJkqHJg== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bMJLb2VyNzyfx; Tue, 17 Jun 2025 20:26:47 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 55HKQldP073158; Tue, 17 Jun 2025 20:26:47 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 55HKQlje073155; Tue, 17 Jun 2025 20:26:47 GMT (envelope-from git) Date: Tue, 17 Jun 2025 20:26:47 GMT Message-Id: <202506172026.55HKQlje073155@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-main@FreeBSD.org From: Cy Schubert Subject: git: 6d669a5d7759 - main - pam-krb5: Add manpage List-Id: Commit messages for the main branch of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-main List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-main@freebsd.org Sender: owner-dev-commits-src-main@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: cy X-Git-Repository: src X-Git-Refname: refs/heads/main X-Git-Reftype: branch X-Git-Commit: 6d669a5d7759ef7657dcc959b826e30d7a5f098b Auto-Submitted: auto-generated The branch main has been updated by cy: URL: https://cgit.FreeBSD.org/src/commit/?id=6d669a5d7759ef7657dcc959b826e30d7a5f098b commit 6d669a5d7759ef7657dcc959b826e30d7a5f098b Author: Cy Schubert AuthorDate: 2025-06-17 16:19:35 +0000 Commit: Cy Schubert CommitDate: 2025-06-17 19:59:37 +0000 pam-krb5: Add manpage To build the man page one must run pod2man on contrib/pam-krb5/docs/pam_krb5.pod and copy it to ${.CURDIR}. --- lib/libpam/modules/pam_krb5/Makefile | 3 + lib/libpam/modules/pam_krb5/pam-krb5.8 | 1025 ++++++++++++++++++++++++++++++++ 2 files changed, 1028 insertions(+) diff --git a/lib/libpam/modules/pam_krb5/Makefile b/lib/libpam/modules/pam_krb5/Makefile index ddd5c17ad259..b537bf37b7f3 100644 --- a/lib/libpam/modules/pam_krb5/Makefile +++ b/lib/libpam/modules/pam_krb5/Makefile @@ -57,6 +57,9 @@ SRCS= account.c \ support.c \ vector.c +MAN= pam-krb5.8 +MLINKS= pam-krb5.8 pam_krb5.8 + CFLAGS= -I${SRCDIR} \ -I${.CURDIR} \ -fno-strict-aliasing \ diff --git a/lib/libpam/modules/pam_krb5/pam-krb5.8 b/lib/libpam/modules/pam_krb5/pam-krb5.8 new file mode 100644 index 000000000000..3413748c7850 --- /dev/null +++ b/lib/libpam/modules/pam_krb5/pam-krb5.8 @@ -0,0 +1,1025 @@ +.\" -*- 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" +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 +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 +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 +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 +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 +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 +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 +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. +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 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 +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 +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 +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 +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 +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" +[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" +[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 +If anonymous PKINIT is not available or fails, FAST will not be used and +the authentication will proceed as normal. +.Sp +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 + 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 +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=" +[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. +The Kerberos PAM module will not meddle with the stored password if it +skips the user due to configuration such as minimum_uid. +.Sp +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" +[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 +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. +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" +[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" +[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 +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 +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=