Mercurial > crates > nonstick

annotate src/module.rs @ 87:05291b601f0a

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Well and truly separate the Linux extensions. This separates the Linux extensions on the libpam side, and disables the two enums on the interface side. Users can still call the Linux extensions from non-Linux PAM impls, but they'll get a conversation error back.
author Paul Fisher <paul@pfish.zone>
date Tue, 10 Jun 2025 04:40:01 -0400
parents 5aa1a010f1e8
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
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,
78
002adfb98c5c Rename files, reorder structs, remove annoying BorrowedBinaryData type.
Paul Fisher <paul@pfish.zone>
parents: 74
diff changeset
31 /// using [`PamShared::get_user`](crate::PamShared::get_user)
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
32 /// and [`PamHandleModule::get_authtok`],
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
33 /// and verify them against something.
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
34 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
35 /// 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
36 /// for more information.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
37 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
38 /// # Valid flags
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 /// 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
41 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
42 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
43 /// - [`Flags::DISALLOW_NULL_AUTHTOK`]
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
44 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
45 /// # Returns
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
46 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
47 /// If the password check was successful, return `Ok(())`.
51
9d1160b02d2c Safety and doc fixes:
Paul Fisher <paul@pfish.zone>
parents: 48
diff changeset
48 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
49 /// Sensible error codes to return include:
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
50 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
51 /// - [`ErrorCode::AuthenticationError`]: Generic authentication error
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
52 /// (like an incorrect password).
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
53 /// - [`ErrorCode::CredentialsInsufficient`]: The application does not have
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
54 /// sufficient credentials to authenticate the user.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
55 /// - [`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
56 /// 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
57 /// - [`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
58 /// - [`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
59 /// They should not try again.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
60 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
61 /// [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
62 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
63 Err(ErrorCode::Ignore)
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
64 }
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
65
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
66 /// Perform "account management".
51
9d1160b02d2c Safety and doc fixes:
Paul Fisher <paul@pfish.zone>
parents: 48
diff changeset
67 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
68 /// 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
69 /// 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
70 /// 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
71 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
72 /// - 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
73 /// - 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
74 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
75 /// 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
76 /// 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
77 /// or really do whatever you want.
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
78 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
79 /// 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
80 /// for more information.
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
81 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
82 /// # Valid flags
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
83 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
84 /// 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
85 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
86 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
87 /// - [`Flags::DISALLOW_NULL_AUTHTOK`]
44
50371046c61a Add support for pam_get_authtok and minor cleanups.
Paul Fisher <paul@pfish.zone>
parents: 34
diff changeset
88 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
89 /// # Returns
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 /// 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
92 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
93 /// 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
94 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
95 /// - [`ErrorCode::AccountExpired`]: The user's account has expired.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
96 /// - [`ErrorCode::AuthenticationError`]: Generic authentication error.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
97 /// - [`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
98 /// 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
99 /// this module in [`Self::change_authtok`].
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
100 /// - [`ErrorCode::PermissionDenied`]: This one is pretty self-explanatory.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
101 /// - [`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
102 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
103 /// [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
104 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
105 Err(ErrorCode::Ignore)
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
106 }
22
4263c1d83d5b Refactor PamHooks into modules mod
Anthony Nowell <anthony@algorithmia.com>
parents: 19
diff changeset
107
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
108 /// Set credentials on this session.
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 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
111 /// 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
112 /// 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
113 /// authentication but before a session is established.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
114 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
115 /// 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
116 /// for more information.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
117 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
118 /// # Valid flags
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
119 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
120 /// This function may be called with the following flags set:
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
121 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
122 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
123 /// - [`Flags::ESTABLISH_CREDENTIALS`]: Initialize credentials for the user.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
124 /// - [`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
125 /// - [`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
126 /// - [`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
127 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
128 /// # Returns
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
129 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
130 /// If credentials were set successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
131 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
132 /// Sensible error codes to return include:
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
133 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
134 /// - [`ErrorCode::CredentialsUnavailable`]: The credentials cannot be retrieved.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
135 /// - [`ErrorCode::CredentialsExpired`]: The credentials have expired.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
136 /// - [`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
137 /// - [`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
138 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
139 /// [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
140 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
141 Err(ErrorCode::Ignore)
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
142 }
22
4263c1d83d5b Refactor PamHooks into modules mod
Anthony Nowell <anthony@algorithmia.com>
parents: 19
diff changeset
143
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
144 // Function for chauthtok modules.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
145
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
146 /// 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
147 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
148 /// PAM calls this function twice in succession.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
149 /// 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
150 /// If the new token is acceptable, return success;
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
151 /// 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
152 /// 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
153 /// 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
154 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
155 /// 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
156 /// for more information.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
157 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
158 /// # Valid flags
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
159 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
160 /// 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
161 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
162 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
163 /// - [`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
164 /// 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
165 /// 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
166 /// - [`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
167 /// just check if the new one is valid.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
168 /// - [`Flags::UPDATE_AUTHTOK`]: Do actually change the password.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
169 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
170 /// # Returns
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
171 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
172 /// If the authentication token was changed successfully
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
173 /// (or the check passed), return `Ok(())`.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
174 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
175 /// Sensible error codes to return include:
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
176 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
177 /// - [`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
178 /// - [`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
179 /// - [`ErrorCode::AuthTokLockBusy`]: The password cannot be changed because
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
180 /// the authentication token is currently locked.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
181 /// - [`ErrorCode::AuthTokDisableAging`]: Aging (expiration) is disabled.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
182 /// - [`ErrorCode::PermissionDenied`]: What it says on the tin.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
183 /// - [`ErrorCode::TryAgain`]: When the preliminary check is unsuccessful,
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
184 /// ask the user for a new authentication token.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
185 /// - [`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
186 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
187 /// [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
188 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
189 Err(ErrorCode::Ignore)
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
190 }
22
4263c1d83d5b Refactor PamHooks into modules mod
Anthony Nowell <anthony@algorithmia.com>
parents: 19
diff changeset
191
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
192 // Functions for session modules.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
193
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
194 /// Called when a session is opened.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
195 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
196 /// 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
197 /// for more information.
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 /// # Valid flags
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
200 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
201 /// The only valid flag is [`Flags::SILENT`].
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
202 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
203 /// # Returns
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
204 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
205 /// If the session was opened successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
206 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
207 /// A sensible error code to return is:
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
208 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
209 /// - [`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
210 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
211 /// [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
212 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
213 Err(ErrorCode::Ignore)
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
214 }
22
4263c1d83d5b Refactor PamHooks into modules mod
Anthony Nowell <anthony@algorithmia.com>
parents: 19
diff changeset
215
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
216 /// Called when a session is being terminated.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
217 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
218 /// 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
219 /// for more information.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
220 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
221 /// # Valid flags
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
222 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
223 /// The only valid flag is [`Flags::SILENT`].
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
224 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
225 /// # Returns
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
226 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
227 /// If the session was closed successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
228 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
229 /// A sensible error code to return is:
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
230 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
231 /// - [`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
232 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
233 /// [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
234 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
235 Err(ErrorCode::Ignore)
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
236 }
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
237 }