view release on metacpan or  search on metacpan

t/data/generate/pam-krb5/output/readme-md  view on Meta::CPAN

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.

## History and Acknowledgements

Originally written by Frank Cusack <fcusack@fcusack.com>, with the
following acknowledgement:

> Thanks to Naomaru Itoi <itoi@eecs.umich.edu>, Curtis King
> <curtis.king@cul.ca>, and Derrick Brashear <shadow@dementia.org>, all of
> whom have written and made available Kerberos 4/5 modules.  Although no
> code in this module is directly from these author's modules, (except the
> get_user_info() routine in support.c; derived from whichever of these
> authors originally wrote the first module the other 2 copied from), it
> was extremely helpful to look over their code which aided in my design.

The module was then patched for the FreeBSD ports collection with
additional modifications by unknown maintainers and then was modified by
Joel Kociolek <joko@logidee.com> to be usable with Debian GNU/Linux.

It was packaged by Sam Hartman as the Kerberos v5 PAM module for Debian
and improved and modified by him and later by Russ Allbery to fix bugs and
add additional features.  It was then adopted by Andres Salomon, who added
support for refreshing credentials.

The current distribution is maintained by Russ Allbery, who also added
support for reading configuration from `krb5.conf`, added many features
for compatibility with the Sourceforge module, commented and standardized
the formatting of the code, and overhauled the documentation.

Thanks to Douglas E. Engert for the initial implementation of PKINIT
support.  I have since modified and reworked it extensively, so any bugs
or compilation problems are my fault.

Thanks to Markus Moeller for lots of debugging and multiple patches and
suggestions for improved portability.

Thanks to Booker Bense for the implementation of the `alt_auth_map`
option.

Thanks to Sam Hartman for the FAST support implementation.

## Support

The [pam-krb5 web page](https://www.eyrie.org/~eagle/software/pam-krb5/)
will always have the current version of this package, the current
documentation, and pointers to any additional resources.

For bug tracking, use the [issue tracker on
GitHub](https://github.com/rra/pam-krb5/issues).  Please be aware that I
tend to be extremely busy and work projects often take priority.  I'll
save your report and get to it as soon as I can, but it may take me a
couple of months.

## Source Repository

pam-krb5 is maintained using Git.  You can access the current source on
[GitHub](https://github.com/rra/pam-krb5) or by cloning the repository at:

https://git.eyrie.org/git/kerberos/pam-krb5.git

or [view the repository on the
web](https://git.eyrie.org/?p=kerberos/pam-krb5.git).

The eyrie.org repository is the canonical one, maintained by the author,
but using GitHub is probably more convenient for most purposes.  Pull
requests are gratefully reviewed and normally accepted.

## License

The pam-krb5 package as a whole is covered by the following copyright
statement and license:

> Copyright 2005-2010, 2014-2015, 2017, 2020-2021
>     Russ Allbery <eagle@eyrie.org>
>
> Copyright 2009-2011
>     The Board of Trustees of the Leland Stanford Junior University
>