view release on metacpan or  search on metacpan

t/data/update/pam-krb5/old/sections/implementation-notes  view on Meta::CPAN

The normal sequence of events when refreshing a ticket cache (such as
inside a screensaver) is:

```
    pam_authenticate
    pam_setcred(PAM_REINITIALIZE_CRED)
    pam_acct_mgmt
```

(`PAM_REFRESH_CRED` may be used instead.)  Authentication proceeds as
above.  At the `pam_setcred` stage, rather than creating a new ticket
cache, the module instead finds the current ticket cache (from the
`KRB5CCNAME` environment variable or the default ticket cache location
from the Kerberos library) and then reinitializes it with the credentials
from the temporary `pam_authenticate` ticket cache.  When refreshing a
ticket cache, the application should not open a session.  Calling
`pam_acct_mgmt` is optional; pam-krb5 doesn't do anything different when
it's called in this case.

If `pam_authenticate` apparently didn't succeed, or if an account was
configured to be ignored via `ignore_root` or `minimum_uid`, `pam_setcred`
(and therefore `pam_open_session`) and `pam_acct_mgmt` return
`PAM_IGNORE`, which tells the PAM library to proceed as if that module
wasn't listed in the PAM configuration at all.  `pam_authenticate`,
however, returns failure in the ignored user case by default, since
otherwise a configuration using `ignore_root` with pam-krb5 as the only
PAM module would allow anyone to log in as root without a password.  There
doesn't appear to be a case where returning `PAM_IGNORE` instead would
improve the module's behavior, but if you know of a case, please let me
know.

By default, `pam_authenticate` intentionally does not follow the PAM
standard for handling expired accounts and instead returns failure from
`pam_authenticate` unless the Kerberos libraries are able to change the
account password during authentication.  Too many applications either do
not call `pam_acct_mgmt` or ignore its exit status.  The fully correct PAM
behavior (returning success from `pam_authenticate` and
`PAM_NEW_AUTHTOK_REQD` from `pam_acct_mgmt`) can be enabled with the
`defer_pwchange` option.

The `defer_pwchange` option is unfortunately somewhat tricky to implement.
In this case, the calling sequence is:

```
    pam_authenticate
    pam_acct_mgmt
    pam_chauthtok
    pam_setcred
    pam_open_session
```

During the first `pam_authenticate`, we can't obtain credentials and
therefore a ticket cache since the password is expired.  But
`pam_authenticate` isn't called again after `pam_chauthtok`, so
`pam_chauthtok` has to create a ticket cache.  We however don't want it to
do this for the normal password change (`passwd`) case.

What we do is set a flag in our PAM data structure saying that we're
processing an expired password, and `pam_chauthtok`, if it sees that flag,
redoes the authentication with password prompting disabled after it
finishes changing the password.

Unfortunately, when handling password changes this way, `pam_chauthtok`
will always have to prompt the user for their current password again even
though they just typed it.  This is because the saved authentication
tokens are cleared after `pam_authenticate` returns, for security reasons.
We could hack around this by saving the password in our PAM data
structure, but this would let the application gain access to it (exactly
what the clearing is intended to prevent) and breaks a PAM library
guarantee.  We could also work around this by having `pam_authenticate`
get the `kadmin/changepw` authenticator in the expired password case and
store it for `pam_chauthtok`, but it doesn't seem worth the hassle.