crates/nonstick: src/module.rs annotate

annotate src/module.rs @ 171:e27c5c667a5a

Create full new types for return code and flags, separate end to end. This plumbs the ReturnCode and RawFlags types through the places where we call into or are called from PAM. Also adds Sun documentation to the project.

author	Paul Fisher <paul@pfish.zone>
date	Fri, 25 Jul 2025 20:52:14 -0400
parents	2f5913131295
children	46e8ce5cd5d1

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
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	6 use crate::constants::{
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	7 AuthnFlags, AuthtokAction, AuthtokFlags, BaseFlags, CredAction, ErrorCode, Result,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	8 };
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	9 use crate::handle::ModuleClient;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	10 use std::ffi::CStr;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	11
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	12 /// A trait for a PAM module to implement.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	13 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	14 /// 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	15 /// (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	16 /// 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	17 /// 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	18 /// 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	19 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	20 /// 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	21 /// and the [PAM Module Writer’s Guide][mwg].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	22 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	23 /// [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	24 /// [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	25 #[allow(unused_variables)]
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	26 pub trait PamModule<T: ModuleClient> {
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	27 // Functions for auth modules.
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 /// Authenticate the user.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	30 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	31 /// 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	32 /// In most cases, you will want to get the user and password,
90 f6186e41399b Miscellaneous fixes and cleanup: Paul Fisher <paul@pfish.zone> parents: 80 diff changeset	33 /// using [`PamShared::username`](crate::PamShared::username)
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 90 diff changeset	34 /// and [`ModuleClient::authtok`],
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	35 /// and verify them against something.
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	36 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	37 /// 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	38 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	39 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	40 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	41 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	42 /// If the password check was successful, return `Ok(())`.
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 48 diff changeset	43 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	44 /// Sensible error codes to return include:
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	45 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	46 /// - [`ErrorCode::AuthenticationError`]: Generic authentication error
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	47 /// (like an incorrect password).
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	48 /// - [`ErrorCode::CredentialsInsufficient`]: The application does not have
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	49 /// sufficient credentials to authenticate the user.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	50 /// - [`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	51 /// 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	52 /// - [`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	53 /// - [`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	54 /// They should not try again.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	55 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	56 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-auth.html#mwg-pam_sm_authenticate
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	57 fn authenticate(handle: &mut T, args: Vec<&CStr>, flags: AuthnFlags) -> Result<()> {
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	58 Err(ErrorCode::Ignore)
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	59 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	60
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	61 /// Perform "account management".
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 48 diff changeset	62 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	63 /// 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	64 /// 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	65 /// 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	66 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	67 /// - 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	68 /// - 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	69 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	70 /// 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	71 /// 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	72 /// or really do whatever you want.
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 /// 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	75 /// for more information.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	76 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	77 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	78 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	79 /// 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	80 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	81 /// 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	82 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	83 /// - [`ErrorCode::AccountExpired`]: The user's account has expired.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	84 /// - [`ErrorCode::AuthenticationError`]: Generic authentication error.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	85 /// - [`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	86 /// 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	87 /// this module in [`Self::change_authtok`].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	88 /// - [`ErrorCode::PermissionDenied`]: This one is pretty self-explanatory.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	89 /// - [`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	90 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	91 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-acct.html#mwg-pam_sm_acct_mgmt
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	92 fn account_management(handle: &mut T, args: Vec<&CStr>, flags: AuthnFlags) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	93 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	94 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	95
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	96 /// Set credentials on this session.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	97 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	98 /// 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	99 /// 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	100 /// 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	101 /// authentication but before a session is established.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	102 ///
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	103 /// The module should perform the specified `action`.
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	104 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	105 /// 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	106 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	107 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	108 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	109 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	110 /// If credentials were set successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	111 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	112 /// Sensible error codes to return include:
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 /// - [`ErrorCode::CredentialsUnavailable`]: The credentials cannot be retrieved.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	115 /// - [`ErrorCode::CredentialsExpired`]: The credentials have expired.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	116 /// - [`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	117 /// - [`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	118 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	119 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-auth.html#mwg-pam_sm_setcred
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	120 fn set_credentials(
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	121 handle: &mut T,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	122 args: Vec<&CStr>,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	123 action: CredAction,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	124 flags: BaseFlags,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	125 ) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	126 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	127 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	128
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	129 // Function for chauthtok modules.
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 /// 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	132 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	133 /// PAM calls this function twice in succession.
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	134 /// 1. The first time, the `action` will be
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	135 /// [`AuthtokAction::Validate`].
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	136 /// If the new token is acceptable, return success;
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	137 /// if not, return [`ErrorCode::TryAgain`] to re-prompt the user.
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	138 /// 2. After the preliminary check succeeds, you will be called again
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	139 /// with the same password and [`AuthtokAction::Update`].
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	140 /// When this happens, actually change the authentication token.
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	141 ///
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	142 /// The new authentication token will be available in
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	143 /// [`authtok`](ModuleClient::authtok),
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	144 /// and the previous authentication token will be available in
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	145 /// [`old_authtok`](ModuleClient::old_authtok).
64 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 /// 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	148 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	149 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	150 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	151 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	152 /// If the authentication token was changed successfully
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	153 /// (or the check passed), return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	154 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	155 /// Sensible error codes to return include:
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 /// - [`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	158 /// - [`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	159 /// - [`ErrorCode::AuthTokLockBusy`]: The password cannot be changed because
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	160 /// the authentication token is currently locked.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	161 /// - [`ErrorCode::AuthTokDisableAging`]: Aging (expiration) is disabled.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	162 /// - [`ErrorCode::PermissionDenied`]: What it says on the tin.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	163 /// - [`ErrorCode::TryAgain`]: When the preliminary check is unsuccessful,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	164 /// ask the user for a new authentication token.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	165 /// - [`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	166 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	167 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-chauthtok.html#mwg-pam_sm_chauthtok
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	168 fn change_authtok(
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	169 handle: &mut T,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	170 args: Vec<&CStr>,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	171 action: AuthtokAction,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	172 flags: AuthtokFlags,
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	173 ) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	174 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	175 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	176
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	177 // Functions for session modules.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	178
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	179 /// Called when a session is opened.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	180 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	181 /// 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	182 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	183 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	184 /// # Returns
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 /// If the session was opened successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	187 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	188 /// A sensible error code to return is:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	189 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	190 /// - [`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	191 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	192 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-of-module-session.html#mwg-pam_sm_open_session
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	193 fn open_session(handle: &mut T, args: Vec<&CStr>, flags: BaseFlags) -> Result<()> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	194 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	195 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	196
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	197 /// Called when a session is being terminated.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	198 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	199 /// 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	200 /// for more information.
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 closed 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 remove 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_close_session
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	211 fn close_session(handle: &mut T, args: Vec<&CStr>, flags: BaseFlags) -> 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 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	214 }

Mercurial > crates > nonstick

annotate src/module.rs @ 171:e27c5c667a5a