crates/nonstick: src/module.rs annotate

annotate src/module.rs @ 74:c7c596e6388f

Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) In previous versions of Conversation, you could send messages and then return messages of the wrong type or in the wrong order or whatever. The receiver would then have to make sure that there were the right number of messages and that each message was the right type. That's annoying. This change makes the `Message` enum a two-way channel, where the asker puts their question into it, and then the answerer (the conversation) puts the answer in and returns control to the asker. The asker then only has to pull the Answer of the type they wanted out of the message.

author	Paul Fisher <paul@pfish.zone>
date	Fri, 06 Jun 2025 22:21:17 -0400
parents	ac6881304c78
children	002adfb98c5c

rev	line source
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	1 //! Functions and types useful for implementing a PAM module.
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	2
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	3 // Temporarily allowed until we get the actual conversation functions hooked up.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	4 #![allow(dead_code)]
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	5
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	6 use crate::constants::{ErrorCode, Flags, Result};
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	7 use crate::handle::PamHandleModule;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	8 use std::ffi::CStr;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	9
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	10 /// A trait for a PAM module to implement.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	11 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	12 /// The default implementations of all these hooks tell PAM to ignore them
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	13 /// (i.e., behave as if this module does not exist) by returning [`ErrorCode::Ignore`].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	14 /// Override any functions you wish to handle in your module.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	15 /// After implementing this trait, use the [`pam_hooks!`](crate::pam_hooks!) macro
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	16 /// to make the functions available to PAM.
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	17 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	18 /// For more information, see [`pam(3)`’s root manual page][manpage]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	19 /// and the [PAM Module Writer’s Guide][mwg].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	20 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	21 /// [manpage]: https://www.man7.org/linux/man-pages/man3/pam.3.html
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	22 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/Linux-PAM_MWG.html
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	23 #[allow(unused_variables)]
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	24 pub trait PamModule<T: PamHandleModule> {
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	25 // Functions for auth modules.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	26
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	27 /// Authenticate the user.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	28 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	29 /// This is probably the first thing you want to implement.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	30 /// In most cases, you will want to get the user and password,
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	31 /// using [`PamHandle::get_user`] and [`PamModuleOnly::get_authtok`],
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	32 /// and verify them against something.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	33 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	34 /// See [the Module Writer's Guide entry for `pam_sm_authenticate`][mwg]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	35 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	36 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	37 /// # Valid flags
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	38 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	39 /// This function may be called with the following flags set:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	40 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	41 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	42 /// - [`Flags::DISALLOW_NULL_AUTHTOK`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	43 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	44 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	45 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	46 /// If the password check was successful, return `Ok(())`.
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 48 diff changeset	47 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	48 /// Sensible error codes to return include:
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	49 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	50 /// - [`ErrorCode::AuthenticationError`]: Generic authentication error
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	51 /// (like an incorrect password).
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	52 /// - [`ErrorCode::CredentialsInsufficient`]: The application does not have
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	53 /// sufficient credentials to authenticate the user.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	54 /// - [`ErrorCode::AuthInfoUnavailable`]: The module was not able to access
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	55 /// the authentication information, for instance due to a network failure.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	56 /// - [`ErrorCode::UserUnknown`]: The supplied username is not known by this service.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	57 /// - [`ErrorCode::MaxTries`]: The user has tried authenticating too many times.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	58 /// They should not try again.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	59 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	60 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-auth.html#mwg-pam_sm_authenticate
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	61 fn authenticate(handle: &mut T, args: Vec<&CStr>, flags: Flags) -> Result<()> {
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	62 Err(ErrorCode::Ignore)
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	63 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	64
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	65 /// Perform "account management".
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 48 diff changeset	66 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	67 /// When PAM calls this function, the user has already been authenticated
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	68 /// by an authentication module (either this one or some other module).
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	69 /// This hook can check for other things, for instance:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	70 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	71 /// - Date/time (keep your kids off the computer at night)
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	72 /// - Remote host (only let employees log in from the office)
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	73 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	74 /// You can also check things like, e.g., password expiration,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	75 /// and alert that the user change it before continuing,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	76 /// or really do whatever you want.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	77 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	78 /// See [the Module Writer's Guide entry for `pam_sm_acct_mgmt`][mwg]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	79 /// for more information.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	80 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	81 /// # Valid flags
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	82 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	83 /// This function may be called with the following flags set:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	84 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	85 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	86 /// - [`Flags::DISALLOW_NULL_AUTHTOK`]
44 50371046c61a Add support for pam_get_authtok and minor cleanups. Paul Fisher <paul@pfish.zone> parents: 34 diff changeset	87 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	88 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	89 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	90 /// If the user should be allowed to log in, return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	91 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	92 /// Sensible error codes to return include:
44 50371046c61a Add support for pam_get_authtok and minor cleanups. Paul Fisher <paul@pfish.zone> parents: 34 diff changeset	93 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	94 /// - [`ErrorCode::AccountExpired`]: The user's account has expired.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	95 /// - [`ErrorCode::AuthenticationError`]: Generic authentication error.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	96 /// - [`ErrorCode::NewAuthTokRequired`]: The user's authentication token has expired.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	97 /// PAM will ask the user to set a new authentication token, which may be handled by
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	98 /// this module in [`Self::change_authtok`].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	99 /// - [`ErrorCode::PermissionDenied`]: This one is pretty self-explanatory.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	100 /// - [`ErrorCode::UserUnknown`]: The supplied username is not known by this service.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	101 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	102 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-acct.html#mwg-pam_sm_acct_mgmt
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	103 fn account_management(handle: &mut T, args: Vec<&CStr>, flags: Flags) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	104 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	105 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	106
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	107 /// Set credentials on this session.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	108 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	109 /// If an authentication module knows more about the user than just
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	110 /// their authentication token, then it uses this function to provide
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	111 /// that information to the application. It should only be called after
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	112 /// authentication but before a session is established.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	113 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	114 /// See [the Module Writer's Guide entry for `pam_sm_setcred`][mwg]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	115 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	116 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	117 /// # Valid flags
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	118 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	119 /// This function may be called with the following flags set:
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	120 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	121 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	122 /// - [`Flags::ESTABLISH_CREDENTIALS`]: Initialize credentials for the user.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	123 /// - [`Flags::DELETE_CREDENTIALS`]: Delete the credentials associated with this module.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	124 /// - [`Flags::REINITIALIZE_CREDENTIALS`]: Re-initialize credentials for this user.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	125 /// - [`Flags::REFRESH_CREDENTIALS`]: Extend the lifetime of the user's credentials.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	126 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	127 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	128 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	129 /// If credentials were set successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	130 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	131 /// Sensible error codes to return include:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	132 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	133 /// - [`ErrorCode::CredentialsUnavailable`]: The credentials cannot be retrieved.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	134 /// - [`ErrorCode::CredentialsExpired`]: The credentials have expired.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	135 /// - [`ErrorCode::CredentialsError`]: Some other error occurred when setting credentials.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	136 /// - [`ErrorCode::UserUnknown`]: The supplied username is not known by this service.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	137 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	138 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-auth.html#mwg-pam_sm_setcred
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	139 fn set_credentials(handle: &mut T, args: Vec<&CStr>, flags: Flags) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	140 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	141 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	142
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	143 // Function for chauthtok modules.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	144
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	145 /// Called to set or reset the user's authentication token.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	146 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	147 /// PAM calls this function twice in succession.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	148 /// 1. The first time, [`Flags::PRELIMINARY_CHECK`] will be set.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	149 /// If the new token is acceptable, return success;
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	150 /// if not, return [`ErrorCode::TryAgain`] to re-prompt the user.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	151 /// 2. After the preliminary check succeeds, [`Flags::UPDATE_AUTHTOK`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	152 /// will be set. On this call, actually update the stored auth token.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	153 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	154 /// See [the Module Writer's Guide entry for `pam_sm_chauthtok`][mwg]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	155 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	156 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	157 /// # Valid flags
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	158 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	159 /// This function may be called with the following flags set:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	160 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	161 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	162 /// - [`Flags::CHANGE_EXPIRED_AUTHTOK`]: This module should only change
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	163 /// any expired passwords, and leave non-expired passwords alone.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	164 /// If present, it _must_ be combined with one of the following.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	165 /// - [`Flags::PRELIMINARY_CHECK`]: Don't actually change the password,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	166 /// just check if the new one is valid.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	167 /// - [`Flags::UPDATE_AUTHTOK`]: Do actually change the password.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	168 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	169 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	170 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	171 /// If the authentication token was changed successfully
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	172 /// (or the check passed), return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	173 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	174 /// Sensible error codes to return include:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	175 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	176 /// - [`ErrorCode::AuthTokError`]: The service could not get the authentication token.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	177 /// - [`ErrorCode::AuthTokRecoveryError`]: The service could not get the old token.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	178 /// - [`ErrorCode::AuthTokLockBusy`]: The password cannot be changed because
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	179 /// the authentication token is currently locked.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	180 /// - [`ErrorCode::AuthTokDisableAging`]: Aging (expiration) is disabled.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	181 /// - [`ErrorCode::PermissionDenied`]: What it says on the tin.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	182 /// - [`ErrorCode::TryAgain`]: When the preliminary check is unsuccessful,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	183 /// ask the user for a new authentication token.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	184 /// - [`ErrorCode::UserUnknown`]: The supplied username is not known by this service.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	185 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	186 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-chauthtok.html#mwg-pam_sm_chauthtok
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	187 fn change_authtok(handle: &mut T, args: Vec<&CStr>, flags: Flags) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	188 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	189 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	190
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	191 // Functions for session modules.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	192
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	193 /// Called when a session is opened.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	194 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	195 /// See [the Module Writer's Guide entry for `pam_sm_open_session`][mwg]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	196 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	197 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	198 /// # Valid flags
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	199 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	200 /// The only valid flag is [`Flags::SILENT`].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	201 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	202 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	203 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	204 /// If the session was opened successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	205 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	206 /// A sensible error code to return is:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	207 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	208 /// - [`ErrorCode::SessionError`]: Cannot make an entry for this session.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	209 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	210 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-session.html#mwg-pam_sm_open_session
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	211 fn open_session(handle: &mut T, args: Vec<&CStr>, flags: Flags) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	212 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	213 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	214
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	215 /// Called when a session is being terminated.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	216 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	217 /// See [the Module Writer's Guide entry for `pam_sm_close_session`][mwg]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	218 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	219 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	220 /// # Valid flags
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	221 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	222 /// The only valid flag is [`Flags::SILENT`].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	223 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	224 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	225 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	226 /// If the session was closed successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	227 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	228 /// A sensible error code to return is:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	229 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	230 /// - [`ErrorCode::SessionError`]: Cannot remove an entry for this session.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	231 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	232 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-session.html#mwg-pam_sm_close_session
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	233 fn close_session(handle: &mut T, args: Vec<&CStr>, flags: Flags) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	234 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	235 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	236 }

Mercurial > crates > nonstick

annotate src/module.rs @ 74:c7c596e6388f