Mercurial > crates > nonstick

annotate src/module.rs @ 173:46e8ce5cd5d1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Miscellaneous doc and code cleanups.
author Paul Fisher <paul@pfish.zone>
date Tue, 29 Jul 2025 16:52:32 -0400
parents e27c5c667a5a
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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.
173
46e8ce5cd5d1 Miscellaneous doc and code cleanups.
Paul Fisher <paul@pfish.zone>
parents: 171
diff changeset
17 /// After implementing this trait, use the [`pam_export!`](crate::pam_export!) macro
64
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 }