crates/nonstick: src/module.rs annotate

annotate src/module.rs @ 70:9f8381a1c09c

Implement low-level conversation primitives. This change does two primary things: 1. Introduces new Conversation traits, to be implemented both by the library and by PAM client applications. 2. Builds the memory-management infrastructure for passing messages through the conversation. ...and it adds tests for both of the above, including ASAN tests.

author	Paul Fisher <paul@pfish.zone>
date	Tue, 03 Jun 2025 01:21:59 -0400
parents	a674799a5cd3
children	58f9d2a4df38

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};
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	7 use crate::conv::BinaryData;
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	8 use crate::conv::{Conversation, Message, Response};
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	9 use crate::handle::PamModuleHandle;
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	10 use secure_string::SecureString;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	11 use std::ffi::CStr;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	12
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	13 /// A trait for a PAM module to implement.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	14 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	15 /// 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	16 /// (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	17 /// 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	18 /// 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	19 /// 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	20 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	21 /// 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	22 /// and the [PAM Module Writer’s Guide][mwg].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	23 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	24 /// [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	25 /// [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	26 #[allow(unused_variables)]
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	27 pub trait PamModule<T: PamModuleHandle> {
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	28 // Functions for auth modules.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	29
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	30 /// Authenticate the user.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	31 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	32 /// 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	33 /// In most cases, you will want to get the user and password,
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	34 /// using [`LibPamHandle::get_user`] and [`LibPamHandle::get_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 /// # Valid flags
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 /// 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	43 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	44 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	45 /// - [`Flags::DISALLOW_NULL_AUTHTOK`]
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 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	48 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	49 /// If the password check was successful, return `Ok(())`.
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 48 diff changeset	50 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	51 /// Sensible error codes to return include:
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	52 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	53 /// - [`ErrorCode::AuthenticationError`]: Generic authentication error
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	54 /// (like an incorrect password).
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	55 /// - [`ErrorCode::CredentialsInsufficient`]: The application does not have
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	56 /// sufficient credentials to authenticate the user.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	57 /// - [`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	58 /// 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	59 /// - [`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	60 /// - [`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	61 /// They should not try again.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	62 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	63 /// [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	64 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	65 Err(ErrorCode::Ignore)
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	66 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	67
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	68 /// Perform "account management".
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 48 diff changeset	69 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	70 /// 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	71 /// 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	72 /// 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	73 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	74 /// - 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	75 /// - 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	76 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	77 /// 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	78 /// 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	79 /// or really do whatever you want.
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	80 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	81 /// 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	82 /// for more information.
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 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	85 /// # Valid flags
19 d654aa0655e5 Making PamHandle a struct with methods Anthony Nowell <anthony@algorithmia.com> parents: 15 diff changeset	86 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	87 /// 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	88 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	89 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	90 /// - [`Flags::DISALLOW_NULL_AUTHTOK`]
44 50371046c61a Add support for pam_get_authtok and minor cleanups. Paul Fisher <paul@pfish.zone> parents: 34 diff changeset	91 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	92 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	93 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	94 /// 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	95 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	96 /// 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	97 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	98 /// - [`ErrorCode::AccountExpired`]: The user's account has expired.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	99 /// - [`ErrorCode::AuthenticationError`]: Generic authentication error.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	100 /// - [`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	101 /// 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	102 /// this module in [`Self::change_authtok`].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	103 /// - [`ErrorCode::PermissionDenied`]: This one is pretty self-explanatory.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	104 /// - [`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	105 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	106 /// [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	107 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	108 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	109 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	110
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	111 /// Set credentials on this session.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	112 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	113 /// 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	114 /// 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	115 /// 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	116 /// authentication but before a session is established.
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 /// 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	119 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	120 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	121 /// # Valid flags
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	122 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	123 /// This function may be called with the following flags set:
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	124 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	125 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	126 /// - [`Flags::ESTABLISH_CREDENTIALS`]: Initialize credentials for the user.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	127 /// - [`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	128 /// - [`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	129 /// - [`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	130 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	131 /// # Returns
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 /// If credentials were set successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	134 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	135 /// Sensible error codes to return include:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	136 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	137 /// - [`ErrorCode::CredentialsUnavailable`]: The credentials cannot be retrieved.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	138 /// - [`ErrorCode::CredentialsExpired`]: The credentials have expired.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	139 /// - [`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	140 /// - [`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	141 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	142 /// [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	143 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	144 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	145 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	146
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	147 // Function for chauthtok modules.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	148
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	149 /// 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	150 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	151 /// PAM calls this function twice in succession.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	152 /// 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	153 /// If the new token is acceptable, return success;
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	154 /// 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	155 /// 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	156 /// 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	157 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	158 /// 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	159 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	160 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	161 /// # Valid flags
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	162 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	163 /// 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	164 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	165 /// - [`Flags::SILENT`]
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	166 /// - [`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	167 /// 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	168 /// 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	169 /// - [`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	170 /// just check if the new one is valid.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	171 /// - [`Flags::UPDATE_AUTHTOK`]: Do actually change the password.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	172 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	173 /// # Returns
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 /// If the authentication token was changed successfully
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	176 /// (or the check passed), return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	177 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	178 /// Sensible error codes to return include:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	179 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	180 /// - [`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	181 /// - [`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	182 /// - [`ErrorCode::AuthTokLockBusy`]: The password cannot be changed because
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	183 /// the authentication token is currently locked.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	184 /// - [`ErrorCode::AuthTokDisableAging`]: Aging (expiration) is disabled.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	185 /// - [`ErrorCode::PermissionDenied`]: What it says on the tin.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	186 /// - [`ErrorCode::TryAgain`]: When the preliminary check is unsuccessful,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	187 /// ask the user for a new authentication token.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	188 /// - [`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	189 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	190 /// [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	191 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	192 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	193 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	194
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	195 // Functions for session modules.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	196
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	197 /// Called when a session is opened.
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_open_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 /// # Valid flags
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 /// The only valid flag is [`Flags::SILENT`].
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 /// # Returns
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 /// If the session was opened successfully, return `Ok(())`.
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 /// A sensible error code to return is:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	211 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	212 /// - [`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	213 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	214 /// [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	215 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	216 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	217 }
22 4263c1d83d5b Refactor PamHooks into modules mod Anthony Nowell <anthony@algorithmia.com> parents: 19 diff changeset	218
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	219 /// Called when a session is being terminated.
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 /// 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	222 /// for more information.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	223 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	224 /// # Valid flags
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	225 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	226 /// The only valid flag is [`Flags::SILENT`].
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	227 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	228 /// # Returns
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	229 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	230 /// If the session was closed successfully, return `Ok(())`.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	231 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	232 /// A sensible error code to return is:
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	233 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	234 /// - [`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	235 ///
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	236 /// [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	237 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	238 Err(ErrorCode::Ignore)
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	239 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	240 }
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	241
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	242 /// Provides methods to make it easier to send exactly one message.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	243 ///
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	244 /// This is primarily used by PAM modules, so that a module that only needs
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	245 /// one piece of information at a time doesn't have a ton of boilerplate.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	246 /// You may also find it useful for testing PAM application libraries.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	247 ///
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	248 /// ```
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	249 /// # use nonstick::Result;
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	250 /// # use nonstick::conv::Conversation;
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	251 /// # use nonstick::module::ConversationMux;
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	252 /// # fn _do_test(conv: impl Conversation) -> Result<()> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	253 /// let mut mux = ConversationMux(conv);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	254 /// let token = mux.masked_prompt("enter your one-time token")?;
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	255 /// # Ok(())
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	256 /// # }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	257 pub struct ConversationMux<C: Conversation>(pub C);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	258
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	259 impl<C: Conversation> Conversation for ConversationMux<C> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	260 fn send(&mut self, messages: &[Message]) -> Result<Vec<Response>> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	261 self.0.send(messages)
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	262 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	263 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	264
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	265 impl<C: Conversation> ConversationMux<C> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	266 /// Prompts the user for something.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	267 pub fn prompt(&mut self, request: &str) -> Result<String> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	268 let resp = self.send(&[Message::Prompt(request)])?.pop();
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	269 match resp {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	270 Some(Response::Text(s)) => Ok(s),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	271 _ => Err(ErrorCode::ConversationError),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	272 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	273 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	274
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	275 /// Prompts the user for something, but hides what the user types.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	276 pub fn masked_prompt(&mut self, request: &str) -> Result<SecureString> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	277 let resp = self.send(&[Message::MaskedPrompt(request)])?.pop();
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	278 match resp {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	279 Some(Response::MaskedText(s)) => Ok(s),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	280 _ => Err(ErrorCode::ConversationError),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	281 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	282 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	283
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	284 /// Prompts the user for a yes/no/maybe conditional (a Linux-PAM extension).
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	285 ///
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	286 /// PAM documentation doesn't define the format of the response.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	287 pub fn radio_prompt(&mut self, request: &str) -> Result<String> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	288 let resp = self.send(&[Message::RadioPrompt(request)])?.pop();
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	289 match resp {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	290 Some(Response::Text(s)) => Ok(s),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	291 _ => Err(ErrorCode::ConversationError),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	292 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	293 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	294
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	295 /// Alerts the user to an error.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	296 pub fn error(&mut self, message: &str) {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	297 let _ = self.send(&[Message::Error(message)]);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	298 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	299
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	300 /// Sends an informational message to the user.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	301 pub fn info(&mut self, message: &str) {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	302 let _ = self.send(&[Message::Info(message)]);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	303 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	304
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	305 /// Requests binary data from the user (a Linux-PAM extension).
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	306 pub fn binary_prompt(&mut self, data: &[u8], data_type: u8) -> Result<BinaryData> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	307 let resp = self
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	308 .send(&[Message::BinaryPrompt { data, data_type }])?
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	309 .pop();
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	310 match resp {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	311 Some(Response::Binary(d)) => Ok(d),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	312 _ => Err(ErrorCode::ConversationError),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	313 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	314 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	315 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	316
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	317 /// Generates the dynamic library entry points for a [PamModule] implementation.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	318 ///
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	319 /// Calling `pam_hooks!(SomeType)` on a type that implements [PamModule] will
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	320 /// generate the exported `extern "C"` functions that PAM uses to call into
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	321 /// your module.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	322 ///
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	323 /// ## Examples:
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	324 ///
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	325 /// Here is full example of a PAM module that would authenticate and authorize everybody:
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	326 ///
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	327 /// ```no_run
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	328 /// use nonstick::{Flags, LibPamHandle, PamModule, PamModuleHandle, Result as PamResult, pam_hooks};
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	329 /// use std::ffi::CStr;
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	330 /// # fn main() {}
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	331 ///
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	332 /// struct MyPamModule;
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	333 /// pam_hooks!(MyPamModule);
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	334 ///
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	335 /// impl<T: PamModuleHandle> PamModule<T> for MyPamModule {
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	336 /// fn authenticate(handle: &mut T, args: Vec<&CStr>, flags: Flags) -> PamResult<()> {
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	337 /// let password = handle.get_authtok(Some("what's your password?"))?;
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	338 /// eprintln!("If you say your password is {:?}, who am I to disagree!", password.unsecure());
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	339 /// Ok(())
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	340 /// }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	341 ///
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	342 /// fn account_management(handle: &mut T, args: Vec<&CStr>, flags: Flags) -> PamResult<()> {
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	343 /// let username = handle.get_user(None)?;
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	344 /// // You should use a Conversation to communicate with the user
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	345 /// // instead of writing to the console, but this is just an example.
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	346 /// eprintln!("Hello {username}! I trust you unconditionally!");
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	347 /// Ok(())
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	348 /// }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	349 /// }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	350 /// ```
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	351 #[macro_export]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	352 macro_rules! pam_hooks {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	353 ($ident:ident) => {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	354 mod _pam_hooks_scope {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	355 use std::ffi::{c_char, c_int, CStr};
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	356 use $crate::{ErrorCode, Flags, LibPamHandle, PamModule};
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	357
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	358 #[no_mangle]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	359 extern "C" fn pam_sm_acct_mgmt(
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	360 pamh: *mut libc::c_void,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	361 flags: Flags,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	362 argc: c_int,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	363 argv: const const c_char,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	364 ) -> c_int {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	365 let args = extract_argv(argc, argv);
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	366 ErrorCode::result_to_c(super::$ident::account_management(
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	367 unsafe { LibPamHandle::from_ptr(pamh) },
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	368 args,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	369 flags,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	370 ))
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	371 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	372
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	373 #[no_mangle]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	374 extern "C" fn pam_sm_authenticate(
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	375 pamh: *mut libc::c_void,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	376 flags: Flags,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	377 argc: c_int,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	378 argv: const const c_char,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	379 ) -> c_int {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	380 let args = extract_argv(argc, argv);
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	381 ErrorCode::result_to_c(super::$ident::authenticate(
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	382 unsafe { LibPamHandle::from_ptr(pamh) },
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	383 args,
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	384 flags,
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	385 ))
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	386 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	387
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	388 #[no_mangle]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	389 extern "C" fn pam_sm_chauthtok(
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	390 pamh: *mut libc::c_void,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	391 flags: Flags,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	392 argc: c_int,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	393 argv: const const c_char,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	394 ) -> c_int {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	395 let args = extract_argv(argc, argv);
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	396 ErrorCode::result_to_c(super::$ident::change_authtok(
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	397 unsafe { LibPamHandle::from_ptr(pamh) },
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	398 args,
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	399 flags,
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	400 ))
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	401 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	402
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	403 #[no_mangle]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	404 extern "C" fn pam_sm_close_session(
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	405 pamh: *mut libc::c_void,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	406 flags: Flags,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	407 argc: c_int,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	408 argv: const const c_char,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	409 ) -> c_int {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	410 let args = extract_argv(argc, argv);
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	411 ErrorCode::result_to_c(super::$ident::close_session(
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	412 unsafe { LibPamHandle::from_ptr(pamh) },
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	413 args,
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	414 flags,
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	415 ))
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	416 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	417
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	418 #[no_mangle]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	419 extern "C" fn pam_sm_open_session(
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	420 pamh: *mut libc::c_void,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	421 flags: Flags,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	422 argc: c_int,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	423 argv: const const c_char,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	424 ) -> c_int {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	425 let args = extract_argv(argc, argv);
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	426 ErrorCode::result_to_c(super::$ident::open_session(
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	427 unsafe { LibPamHandle::from_ptr(pamh) },
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	428 args,
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	429 flags,
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	430 ))
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	431 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	432
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	433 #[no_mangle]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	434 extern "C" fn pam_sm_setcred(
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	435 pamh: *mut libc::c_void,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	436 flags: Flags,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	437 argc: c_int,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	438 argv: const const c_char,
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	439 ) -> c_int {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	440 let args = extract_argv(argc, argv);
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	441 ErrorCode::result_to_c(super::$ident::set_credentials(
66 a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits. Paul Fisher <paul@pfish.zone> parents: 64 diff changeset	442 unsafe { LibPamHandle::from_ptr(pamh) },
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	443 args,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	444 flags,
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	445 ))
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	446 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	447
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	448 /// Turns `argc`/`argv` into a [Vec] of [CStr]s.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	449 ///
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	450 /// # Safety
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	451 ///
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	452 /// We use this only with arguments we get from `libpam`, which we kind of have to trust.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	453 fn extract_argv<'a>(argc: c_int, argv: const const c_char) -> Vec<&'a CStr> {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	454 (0..argc)
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	455 .map(\|o\| unsafe { CStr::from_ptr(argv.offset(o as isize) as const c_char) })
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	456 .collect()
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	457 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	458 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	459 };
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	460 }
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	461
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	462 #[cfg(test)]
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	463 mod test {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	464 use super::{
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	465 Conversation, ConversationMux, ErrorCode, Message, Response, Result, SecureString,
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	466 };
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	467
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	468 /// Compile-time test that the `pam_hooks` macro compiles.
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	469 mod hooks {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	470 use super::super::{PamModule, PamModuleHandle};
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	471 struct Foo;
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	472 impl<T: PamModuleHandle> PamModule<T> for Foo {}
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	473
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	474 pam_hooks!(Foo);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	475 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	476
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	477 #[test]
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	478 fn test_mux() {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	479 struct MuxTester;
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	480
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	481 impl Conversation for MuxTester {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	482 fn send(&mut self, messages: &[Message]) -> Result<Vec<Response>> {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	483 if let [msg] = messages {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	484 match msg {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	485 Message::Info(info) => {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	486 assert_eq!("let me tell you", *info);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	487 Ok(vec![Response::NoResponse])
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	488 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	489 Message::Error(error) => {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	490 assert_eq!("oh no", *error);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	491 Ok(vec![Response::NoResponse])
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	492 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	493 Message::Prompt("should_error") => Err(ErrorCode::BufferError),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	494 Message::Prompt(ask) => {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	495 assert_eq!("question", *ask);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	496 Ok(vec![Response::Text("answer".to_owned())])
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	497 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	498 Message::MaskedPrompt("return_wrong_type") => {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	499 Ok(vec![Response::NoResponse])
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	500 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	501 Message::MaskedPrompt(ask) => {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	502 assert_eq!("password!", *ask);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	503 Ok(vec![Response::MaskedText(SecureString::from(
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	504 "open sesame",
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	505 ))])
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	506 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	507 Message::BinaryPrompt { data, data_type } => {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	508 assert_eq!(&[1, 2, 3], data);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	509 assert_eq!(69, *data_type);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	510 Ok(vec![Response::Binary(super::BinaryData::new(
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	511 vec![3, 2, 1],
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	512 42,
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	513 ))])
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	514 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	515 Message::RadioPrompt(ask) => {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	516 assert_eq!("radio?", *ask);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	517 Ok(vec![Response::Text("yes".to_owned())])
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	518 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	519 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	520 } else {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	521 panic!("messages is the wrong size ({len})", len = messages.len())
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	522 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	523 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	524 }
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	525
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	526 let mut mux = ConversationMux(MuxTester);
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	527 assert_eq!("answer", mux.prompt("question").unwrap());
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	528 assert_eq!(
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	529 SecureString::from("open sesame"),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	530 mux.masked_prompt("password!").unwrap()
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	531 );
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	532 mux.error("oh no");
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	533 mux.info("let me tell you");
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	534 {
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	535 assert_eq!("yes", mux.radio_prompt("radio?").unwrap());
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	536 assert_eq!(
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	537 super::BinaryData::new(vec![3, 2, 1], 42),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	538 mux.binary_prompt(&[1, 2, 3], 69).unwrap(),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	539 )
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	540 }
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	541 assert_eq!(
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	542 ErrorCode::BufferError,
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	543 mux.prompt("should_error").unwrap_err(),
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	544 );
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	545 assert_eq!(
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	546 ErrorCode::ConversationError,
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	547 mux.masked_prompt("return_wrong_type").unwrap_err()
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	548 )
9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 66 diff changeset	549 }
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	550 }

Mercurial > crates > nonstick

annotate src/module.rs @ 70:9f8381a1c09c