Mercurial > crates > nonstick

comparison pam/src/hooks.rs @ 21:aa7e8bd083ef

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
add more docs and other cleanup
author Anthony Nowell <anthony@algorithmia.com>
date Tue, 26 Sep 2017 02:15:28 -0600
parents 734ca62159fb
children
comparison
equal deleted inserted replaced
20:734ca62159fb 21:aa7e8bd083ef
1 use module::{PamHandle}; 1 use module::{PamHandle};
2 use constants::{PamFlag, PamResultCode}; 2 use constants::{PamFlag, PamResultCode};
3 use std::ffi::CStr; 3 use std::ffi::CStr;
4 4
5 /// Provides functions that are invoked by the entrypoints generated by the `pam_hooks!` macro. 5 /// Provides functions that are invoked by the entrypoints generated by the
6 /// [`pam_hooks!` macro](../macro.pam_hooks.html).
6 /// 7 ///
7 /// All of hooks are ignored by PAM dispatch by default given the default return value of `PAM_IGNORE`. 8 /// All of hooks are ignored by PAM dispatch by default given the default return value of `PAM_IGNORE`.
8 /// Override any functions that you want to handle with your module. See `man pam(3)`. 9 /// Override any functions that you want to handle with your module. See `man pam(3)`.
10 #[allow(unused_variables)]
9 pub trait PamHooks { 11 pub trait PamHooks {
10 /// This function performs the task of establishing whether the user is permitted to gain access at 12 /// This function performs the task of establishing whether the user is permitted to gain access at
11 /// this time. It should be understood that the user has previously been validated by an 13 /// this time. It should be understood that the user has previously been validated by an
12 /// authentication module. This function checks for other things. Such things might be: the time of 14 /// authentication module. This function checks for other things. Such things might be: the time of
13 /// day or the date, the terminal line, remote hostname, etc. This function may also determine 15 /// day or the date, the terminal line, remote hostname, etc. This function may also determine
14 /// things like the expiration on passwords, and respond that the user change it before continuing. 16 /// things like the expiration on passwords, and respond that the user change it before continuing.
15 fn acct_mgmt(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode { 17 fn acct_mgmt(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
16 PamResultCode::PAM_IGNORE 18 PamResultCode::PAM_IGNORE
17 } 19 }
18 20
19 /// This function performs the task of authenticating the user. 21 /// This function performs the task of authenticating the user.
20 fn sm_authenticate(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode { 22 fn sm_authenticate(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
21 PamResultCode::PAM_IGNORE 23 PamResultCode::PAM_IGNORE
22 } 24 }
23 25
24 /// This function is used to (re-)set the authentication token of the user. 26 /// This function is used to (re-)set the authentication token of the user.
25 /// 27 ///
26 /// The PAM library calls this function twice in succession. The first time with 28 /// The PAM library calls this function twice in succession. The first time with
27 /// PAM_PRELIM_CHECK and then, if the module does not return PAM_TRY_AGAIN, subsequently with 29 /// PAM_PRELIM_CHECK and then, if the module does not return PAM_TRY_AGAIN, subsequently with
28 /// PAM_UPDATE_AUTHTOK. It is only on the second call that the authorization token is 30 /// PAM_UPDATE_AUTHTOK. It is only on the second call that the authorization token is
29 /// (possibly) changed. 31 /// (possibly) changed.
30 fn sm_chauthtok(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode { 32 fn sm_chauthtok(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
31 PamResultCode::PAM_IGNORE 33 PamResultCode::PAM_IGNORE
32 } 34 }
33 35
34 /// This function is called to terminate a session. 36 /// This function is called to terminate a session.
35 fn sm_close_session(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode { 37 fn sm_close_session(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
36 PamResultCode::PAM_IGNORE 38 PamResultCode::PAM_IGNORE
37 } 39 }
38 40
39 /// This function is called to commence a session. 41 /// This function is called to commence a session.
40 fn sm_open_session(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode { 42 fn sm_open_session(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
41 PamResultCode::PAM_IGNORE 43 PamResultCode::PAM_IGNORE
42 } 44 }
43 45
44 /// This function performs the task of altering the credentials of the user with respect to the 46 /// This function performs the task of altering the credentials of the user with respect to the
45 /// corresponding authorization scheme. Generally, an authentication module may have access to more 47 /// corresponding authorization scheme. Generally, an authentication module may have access to more
46 /// information about a user than their authentication token. This function is used to make such 48 /// information about a user than their authentication token. This function is used to make such
47 /// information available to the application. It should only be called after the user has been 49 /// information available to the application. It should only be called after the user has been
48 /// authenticated but before a session has been established. 50 /// authenticated but before a session has been established.
49 fn sm_setcred(_pamh: &PamHandle, _args: Vec<&CStr>, _flags: PamFlag) -> PamResultCode { 51 fn sm_setcred(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
50 PamResultCode::PAM_IGNORE 52 PamResultCode::PAM_IGNORE
51 } 53 }
52 } 54 }
53 55
54 /// Macro to generate the `extern "C"` entrypoint bindings needed by PAM 56 /// Macro to generate the `extern "C"` entrypoint bindings needed by PAM
55 /// 57 ///
56 /// You can call `pam_hooks!(SomeType);` for any type that implements `PamHooks` 58 /// You can call `pam_hooks!(SomeType);` for any type that implements `PamHooks`
59 ///
60 /// ## Examples:
61 ///
62 /// Here is full example of a PAM module that would authenticate and authorize everybody:
63 ///
64 /// ```
65 /// #[macro_use] extern crate pam;
66 ///
67 /// use pam::hooks::PamHooks;
68 /// use pam::module::PamHandle;
69 /// use pam::constants::{PamResultCode, PamFlag};
70 /// use std::ffi::CStr;
71 ///
72 /// # fn main() {}
73 /// struct MyPamModule;
74 /// pam_hooks!(MyPamModule);
75 ///
76 /// impl PamHooks for MyPamModule {
77 /// fn sm_authenticate(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
78 /// println!("Everybody is authenticated!");
79 /// PamResultCode::PAM_SUCCESS
80 /// }
81 ///
82 /// fn acct_mgmt(pamh: &PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
83 /// println!("Everybody is authorized!");
84 /// PamResultCode::PAM_SUCCESS
85 /// }
86 /// }
87 /// ```
57 #[macro_export] 88 #[macro_export]
58 macro_rules! pam_hooks { 89 macro_rules! pam_hooks {
59 ($ident:ident) => ( 90 ($ident:ident) => (
60 pub use pam_hooks_scope::*; 91 pub use self::pam_hooks_scope::*;
61 mod pam_hooks_scope { 92 mod pam_hooks_scope {
62 use $crate::module::PamHandle; 93 use $crate::module::PamHandle;
63 use $crate::constants::{PamFlag, PamResultCode}; 94 use $crate::constants::{PamFlag, PamResultCode};
64 use $crate::hooks::PamHooks; 95 use $crate::hooks::PamHooks;
65 use std::ffi::CStr; 96 use std::ffi::CStr;