crates/nonstick: src/conv.rs annotate

annotate src/conv.rs @ 64:bbe84835d6db v0.0.5

More organization; add lots of docs. - moves `PamHandle` to its own module, since it will be used by both modules and clients. - adds a ton of documentation to the `PamModule` trait and reorders methods to most-interesting-first. - adds more flag values from pam_modules.h. - other misc cleanup.

author	Paul Fisher <paul@pfish.zone>
date	Thu, 22 May 2025 01:52:32 -0400
parents	a7aa5ca0d00d
children

rev	line source
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	1 //! The [Conversation] struct, for interacting with the user.
62 d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	2 //!
d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	3 //! This module is experimental and will probably be rewritten in the future
d83623951070 Further improve docs and put `conv` behind a feature gate. Paul Fisher <paul@pfish.zone> parents: 60 diff changeset	4 //! to improve the interface for both PAM modules and clients.
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	5
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 63 diff changeset	6 use crate::constants::MessageStyle;
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 63 diff changeset	7 use crate::constants::Result;
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 63 diff changeset	8 use crate::constants::{ErrorCode, InvalidEnum};
bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 63 diff changeset	9 use crate::items::Item;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	10 use libc::{c_char, c_int};
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 63 diff changeset	11 use num_derive::FromPrimitive;
27 0ceeffe67ec4 style: rustfmt holycleugh <holycleugh> parents: 15 diff changeset	12 use std::ffi::{CStr, CString};
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	13 use std::ptr;
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	14
63 a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	15 /// Styles of message that are shown to the user.
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	16 #[derive(Debug, PartialEq, FromPrimitive)]
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	17 #[non_exhaustive] // non-exhaustive because C might give us back anything!
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	18 pub enum MessageStyle {
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	19 /// Requests information from the user; will be masked when typing.
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	20 PromptEchoOff = 1,
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	21 /// Requests information from the user; will not be masked.
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	22 PromptEchoOn = 2,
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	23 /// An error message.
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	24 ErrorMsg = 3,
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	25 /// An informational message.
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	26 TextInfo = 4,
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	27 /// Yes/No/Maybe conditionals. Linux-PAM specific.
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	28 RadioType = 5,
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	29 /// For server–client non-human interaction.
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	30 /// NOT part of the X/Open PAM specification.
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	31 BinaryPrompt = 7,
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	32 }
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	33
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	34 impl TryFrom<c_int> for MessageStyle {
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	35 type Error = InvalidEnum<Self>;
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	36 fn try_from(value: c_int) -> std::result::Result<Self, Self::Error> {
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	37 Self::from_i32(value).ok_or(value.into())
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	38 }
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	39 }
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	40
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	41 impl From<MessageStyle> for c_int {
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	42 fn from(val: MessageStyle) -> Self {
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	43 val as Self
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	44 }
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	45 }
a7aa5ca0d00d Move MessageStyle to conv, the only place it is used. Paul Fisher <paul@pfish.zone> parents: 62 diff changeset	46
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	47 #[repr(C)]
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	48 struct Message {
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	49 msg_style: MessageStyle,
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	50 msg: *const c_char,
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	51 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	52
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	53 #[repr(C)]
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	54 struct Response {
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	55 resp: *const c_char,
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	56 resp_retcode: libc::c_int, // Unused - always zero
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	57 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	58
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	59 #[doc(hidden)]
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	60 #[repr(C)]
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	61 pub struct Inner {
27 0ceeffe67ec4 style: rustfmt holycleugh <holycleugh> parents: 15 diff changeset	62 conv: extern "C" fn(
0ceeffe67ec4 style: rustfmt holycleugh <holycleugh> parents: 15 diff changeset	63 num_msg: c_int,
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	64 pam_message: &&Message,
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	65 pam_response: &mut *const Response,
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	66 appdata_ptr: *const libc::c_void,
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	67 ) -> c_int,
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	68 appdata_ptr: *const libc::c_void,
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	69 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	70
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	71 /// A communication channel with the user.
51 9d1160b02d2c Safety and doc fixes: Paul Fisher <paul@pfish.zone> parents: 48 diff changeset	72 ///
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	73 /// Use this to communicate with the user, if needed, beyond the standard
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	74 /// things you can get/set with `get_user`/`get_authtok` and friends.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	75 /// The PAM client (i.e., the application that is logging in) will present
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	76 /// the messages you send to the user and ask for responses.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	77 pub struct Conversation<'a>(&'a Inner);
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	78
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	79 impl Conversation<'_> {
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	80 /// Sends a message to the PAM client.
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	81 ///
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	82 /// This will typically result in the user seeing a message or a prompt.
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	83 /// For details, see what [MessageStyle]s are available.
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	84 ///
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	85 /// Note that the user experience will depend on how each style
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	86 /// is implemented by the client, and that not all clients
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	87 /// will implement all message styles.
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	88 pub fn send(&self, style: MessageStyle, msg: &str) -> Result<Option<&CStr>> {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	89 let mut resp_ptr: *const Response = ptr::null();
28 81a9f0479e50 conv: fix bug where pam prompts were not being shown holycleugh <holycleugh> parents: 27 diff changeset	90 let msg_cstr = CString::new(msg).unwrap();
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	91 let msg = Message {
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	92 msg_style: style,
28 81a9f0479e50 conv: fix bug where pam prompts were not being shown holycleugh <holycleugh> parents: 27 diff changeset	93 msg: msg_cstr.as_ptr(),
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	94 };
59 3f4a77aa88be Fix string copyting and improve error situation. Paul Fisher <paul@pfish.zone> parents: 56 diff changeset	95 // TODO: These need to be freed!
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	96 let ret = (self.0.conv)(1, &&msg, &mut resp_ptr, self.0.appdata_ptr);
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	97 ErrorCode::result_from(ret)?;
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	98
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	99 let result = unsafe {
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	100 match (*resp_ptr).resp {
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	101 p if p.is_null() => None,
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	102 p => Some(CStr::from_ptr(p)),
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	103 }
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	104 };
daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	105 Ok(result)
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	106 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	107 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	108
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 59 diff changeset	109 impl Item for Conversation<'_> {
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	110 type Raw = Inner;
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	111
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	112 fn type_id() -> crate::items::ItemType {
56 daa2cde64601 Big big refactor. Probably should have been multiple changes. Paul Fisher <paul@pfish.zone> parents: 51 diff changeset	113 crate::items::ItemType::Conversation
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	114 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	115
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	116 unsafe fn from_raw(raw: *const Self::Raw) -> Self {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	117 Self(&*raw)
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	118 }
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	119
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	120 fn into_raw(self) -> *const Self::Raw {
ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 31 diff changeset	121 self.0 as _
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	122 }
27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	123 }

Mercurial > crates > nonstick

annotate src/conv.rs @ 64:bbe84835d6db v0.0.5