Mercurial > crates > nonstick

comparison src/items.rs @ 146:1bc52025156b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Split PAM items into their own separate struct. To trim down the number of methods on `PamShared`, this puts all the Items into their own struct(s). This also makes the split between authtok/authtok_item easier to understand.
author Paul Fisher <paul@pfish.zone>
date Sun, 06 Jul 2025 19:10:26 -0400
parents
children
comparison
equal deleted inserted replaced
145:8f964b701652 146:1bc52025156b
1 use crate::_doc::{guide, linklist, stdlinks};
2 use crate::constants::Result;
3 #[cfg(doc)]
4 use crate::handle::{ModuleClient, PamShared};
5 use std::ffi::{OsStr, OsString};
6
7 macro_rules! getter {
8 ($(#[$md:meta])* $getter:ident($item:literal $(, see = $see:path)?)) => {
9 $(#[$md])*
10 #[doc = ""]
11 #[doc = concat!("Gets the `", $item, "` of the PAM handle.")]
12 $(
13 #[doc = concat!("See [`", stringify!($see), "`].")]
14 )?
15 fn $getter(&self) -> Result<Option<OsString>>;
16 };
17 }
18
19 pub(crate) use getter;
20 macro_rules! setter {
21 ($(#[$md:meta])* $setter:ident($item:literal $(, see = $see:path)?)) => {
22 $(#[$md])*
23 #[doc = ""]
24 #[doc = concat!("Sets the `", $item, "` from the PAM handle.")]
25 $(
26 #[doc = concat!("See [`", stringify!($see), "`].")]
27 )?
28 ///
29 /// Sets the item's value. PAM copies the string's contents.
30 ///
31 /// # Panics
32 ///
33 /// If the string contains a nul byte, this will panic.
34 ///
35 fn $setter(&mut self, value: Option<&OsStr>) -> Result<()>;
36 };
37 }
38
39 /// Provides access to Items, pieces of data shared by the PAM application,
40 /// modules, and the framework itself.
41 ///
42 /// # References
43 ///
44 #[doc = linklist!(pam_get_item: mwg, adg, _std)]
45 ///
46 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_get_item")]
47 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_item")]
48 #[doc = stdlinks!(3 pam_get_item)]
49 pub trait Items<'a> {
50 getter!(
51 /// The identity of the user for whom service is being requested.
52 ///
53 /// Unlike [`username`](PamShared::username), this will simply get
54 /// the current state of the user item, and not request the username.
55 /// While PAM usually sets this automatically in the `username` call,
56 /// it may be changed by a module during the PAM transaction.
57 /// Applications should check it after each step of the PAM process.
58 user("PAM_USER", see = PamShared::username)
59 );
60
61 getter!(
62 /// If set, the identity of the remote user logging in.
63 ///
64 /// This is only as trustworthy as the application calling PAM.
65 remote_user("PAM_RUSER", see = Self::remote_host)
66 );
67
68 getter!(
69 /// If set, the remote location where the user is coming from.
70 ///
71 /// This is only as trustworthy as the application calling PAM.
72 /// This can be combined with [`Self::remote_user`] to identify
73 /// the account the user is attempting to log in from,
74 /// with `remote_user@remote_host`.
75 ///
76 /// If unset, "it is unclear where the authentication request
77 /// is originating from."
78 remote_host("PAM_RHOST", see = Self::remote_user)
79 );
80
81 getter!(
82 /// The service name, which identifies the PAM stack which is used
83 /// to perform authentication.
84 service("PAM_SERVICE")
85 );
86
87 getter!(
88 /// The string used to prompt for a user's name.
89 /// By default, this is a localized version of `login: `.
90 user_prompt("PAM_USER_PROMPT")
91 );
92
93 getter!(
94 /// The device path of the TTY being used to log in.
95 ///
96 /// This is the terminal the user is logging in on,
97 /// specified as the full device path (e.g. `/dev/tty0`).
98 /// Very old applications may use this instead of `PAM_XDISPLAY`.
99 tty_name("PAM_TTY")
100 );
101 }
102
103 /// Provides write access to PAM Items, data shared by the PAM application,
104 /// the framework, and modules.
105 ///
106 /// # References
107 ///
108 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
109 ///
110 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
111 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
112 #[doc = stdlinks!(3 pam_set_item)]
113 pub trait ItemsMut<'a>: Items<'a> {
114 setter!(
115 /// Sets the identity of the logging-in user.
116 ///
117 /// Usually this will be set during the course of
118 /// a [`username`](PamShared::username) call, but you may set it manually
119 /// or change it during the PAM process.
120 set_user("PAM_USER", see = Items::user)
121 );
122
123 setter!(
124 /// Sets the service name. It's probably a bad idea to change this.
125 set_service("PAM_SERVICE", see = Items::service)
126 );
127
128 setter!(
129 /// Sets the string used to prompt for a user's name.
130 set_user_prompt("PAM_USER_PROMPT", see = Items::user_prompt)
131 );
132
133 setter!(
134 /// Sets the path to the terminal where the user is logging on.
135 set_tty_name("PAM_TTY", see = Items::tty_name)
136 );
137
138 setter!(
139 /// Sets the identity of the remote user logging in.
140 ///
141 /// This may be set by the application before making calls
142 /// into a PAM transaction.
143 set_remote_user("PAM_RUSER", see = Items::remote_user)
144 );
145
146 setter!(
147 /// Sets the location where the user is coming from.
148 ///
149 /// This may be set by the application before making calls
150 /// into a PAM transaction.
151 set_remote_host("PAM_RHOST", see = Items::remote_host)
152 );
153
154 setter!(
155 /// Gets the user's authentication token (e.g., password).
156 ///
157 /// This is usually set automatically when
158 /// [`authtok`](ModuleClient::authtok) is called,
159 /// but can be manually set.
160 set_authtok("PAM_AUTHTOK", see = ModuleClient::authtok_item)
161 );
162 setter!(
163 /// Sets the user's "old authentication token" when changing passwords.
164 ///
165 /// This is usually set automatically by PAM when
166 /// [`old_authtok`](ModuleClient::old_authtok) is called.
167 set_old_authtok("PAM_OLDAUTHTOK", see = ModuleClient::old_authtok_item)
168 );
169 }