Mercurial > crates > nonstick

annotate src/handle.rs @ 103:dfcd96a74ac4 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
write a truly prodigious amount of documentation adds a bunch of links to the OpenPAM man pages and the XSSO spec as well as just a bunch of prose and stuff.
author Paul Fisher <paul@pfish.zone>
date Wed, 25 Jun 2025 00:59:24 -0400
parents 3f11b8d30f63
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
66
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
1 //! The wrapper types and traits for handles into the PAM library.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
2
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
3 use crate::constants::{Flags, Result};
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
4 use crate::conv::Conversation;
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
5 use crate::environ::{EnvironMap, EnvironMapMut};
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
6 use crate::logging::Level;
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
7 use crate::{_guide, _linklist, _man7, _manbsd, _stdlinks};
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
8
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
9 macro_rules! trait_item {
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
10 ($(#[$md:meta])* get = $getter:ident, item = $item:literal $(, see = $see:path)?) => {
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
11 $(#[$md])*
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
12 #[doc = ""]
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
13 #[doc = concat!("Gets the `", $item, "` of the PAM handle.")]
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
14 $(
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
15 #[doc = concat!("See [`", stringify!($see), "`].")]
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
16 )?
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
17 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
18 /// Returns a reference to the item's value, owned by PAM.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
19 /// The item is assumed to be valid UTF-8 text.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
20 /// If it is not, `ConversationError` is returned.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
21 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
22 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
23 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
24 #[doc = _linklist!(pam_get_item: mwg, adg, _std)]
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
25 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
26 #[doc = _guide!(adg: "adg-interface-by-app-expected.html#adg-pam_get_item")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
27 #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_item")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
28 #[doc = _stdlinks!(3 pam_get_item)]
95
51c9d7e8261a Return owned strings rather than borrowed strings.
Paul Fisher <paul@pfish.zone>
parents: 94
diff changeset
29 fn $getter(&self) -> Result<Option<String>>;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
30 };
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
31 ($(#[$md:meta])* set = $setter:ident, item = $item:literal $(, see = $see:path)?) => {
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
32 $(#[$md])*
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
33 #[doc = ""]
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
34 #[doc = concat!("Sets the `", $item, "` from the PAM handle.")]
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
35 $(
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
36 #[doc = concat!("See [`", stringify!($see), "`].")]
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
37 )?
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
38 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
39 /// Sets the item's value. PAM copies the string's contents.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
40 /// If the string contains a null byte, this will return
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
41 /// a `ConversationError`.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
42 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
43 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
44 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
45 #[doc = _linklist!(pam_set_item: mwg, adg, _std)]
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
46 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
47 #[doc = _guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
48 #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
49 #[doc = _stdlinks!(3 pam_set_item)]
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
50 fn $setter(&mut self, value: Option<&str>) -> Result<()>;
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
51 };
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
52 }
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
53
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
54 /// Functionality for both PAM applications and PAM modules.
56
daa2cde64601 Big big refactor. Probably should have been multiple changes.
Paul Fisher <paul@pfish.zone>
parents: 51
diff changeset
55 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
56 /// This base trait includes features of a PAM handle that are available
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
57 /// to both applications and modules.
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
58 ///
75
c30811b4afae rename pam_ffi submodule to libpam.
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
59 /// You probably want [`LibPamHandle`](crate::libpam::OwnedLibPamHandle).
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
60 /// This trait is intended to allow creating mock PAM handle types
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
61 /// to test PAM modules and applications.
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
62 pub trait PamShared {
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
63 /// Logs something via this PAM handle.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
64 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
65 /// You probably want to use one of the logging macros,
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
66 /// like [`error!`](crate::error!),
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
67 /// [`warn!`](crate::warn!),
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
68 /// [`info!`](crate::info!),
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
69 /// or [`debug!`](crate::debug!).
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
70 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
71 /// In most PAM implementations, this will go to syslog.
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
72 /// See [Linux-PAM's `pam_syslog`][man7] or
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
73 /// [OpenPAM's `openpam_log`][manbsd] for more details.
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
74 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
75 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
76 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
77 /// ```no_run
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
78 /// # use nonstick::{PamShared};
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
79 /// # use nonstick::logging::Level;
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
80 /// # fn _test(pam_hdl: impl PamShared) {
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
81 /// # let delay_ms = 100;
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
82 /// # let url = "https://zombo.com";
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
83 /// // Usually, instead of calling this manually, just use the macros.
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
84 /// nonstick::error!(pam_hdl, "something bad happened!");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
85 /// nonstick::warn!(pam_hdl, "loading information took {delay_ms} ms");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
86 /// nonstick::info!(pam_hdl, "using network backend");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
87 /// nonstick::debug!(pam_hdl, "sending GET request to {url}");
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
88 /// // But if you really want to, you can call this yourself:
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
89 /// pam_hdl.log(Level::Warning, "this is unnecessarily verbose");
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
90 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
91 /// ```
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
92 #[doc = _man7!(3 pam_syslog)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
93 #[doc = _manbsd!(3 openpam_log)]
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
94 fn log(&self, level: Level, entry: &str);
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
95
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
96 /// Retrieves the name of the user who is authenticating or logging in.
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
97 ///
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
98 /// If the username has previously been obtained, this uses that username;
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
99 /// otherwise it prompts the user with the first of these that is present:
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
100 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
101 /// 1. The prompt string passed to this function.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
102 /// 2. The string returned by `get_user_prompt_item`.
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
103 /// 3. The default prompt, `login: `.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
104 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
105 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
106 #[doc = _linklist!(pam_get_user: mwg, _std)]
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
107 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
108 /// # Example
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
109 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
110 /// ```no_run
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
111 /// # use nonstick::PamShared;
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
112 /// # fn _doc(handle: &mut impl PamShared) -> Result<(), Box<dyn std::error::Error>> {
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
113 /// // Get the username using the default prompt.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
114 /// let user = handle.username(None)?;
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
115 /// // Get the username using a custom prompt.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
116 /// // If this were actually called right after the above,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
117 /// // both user and user_2 would have the same value.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
118 /// let user_2 = handle.username(Some("who ARE you even???"))?;
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
119 /// # Ok(())
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 /// ```
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
122 #[doc = _stdlinks!(3 pam_get_user)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
123 #[doc = _guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
95
51c9d7e8261a Return owned strings rather than borrowed strings.
Paul Fisher <paul@pfish.zone>
parents: 94
diff changeset
124 fn username(&mut self, prompt: Option<&str>) -> Result<String>;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
125
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
126 /// The contents of the environment to set, read-only.
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
127 fn environ(&self) -> impl EnvironMap;
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
128
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
129 /// A writable version of the environment.
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
130 fn environ_mut(&mut self) -> impl EnvironMapMut;
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
131
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
132 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
133 /// The identity of the user for whom service is being requested.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
134 ///
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
135 /// Unlike [`username`](Self::username), this will simply get
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
136 /// the current state of the user item, and not request the username.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
137 /// While PAM usually sets this automatically in the `username` call,
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
138 /// it may be changed by a module during the PAM transaction.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
139 /// Applications should check it after each step of the PAM process.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
140 get = user_item,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
141 item = "PAM_USER",
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
142 see = Self::username
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
143 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
144 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
145 /// Sets the identity of the logging-in user.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
146 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
147 /// Usually this will be set during the course of
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
148 /// a [`username`](Self::username) call, but you may set it manually
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
149 /// or change it during the PAM process.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
150 set = set_user_item,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
151 item = "PAM_USER",
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
152 see = Self::user_item
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
153 );
44
50371046c61a Add support for pam_get_authtok and minor cleanups.
Paul Fisher <paul@pfish.zone>
parents: 34
diff changeset
154
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
155 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
156 /// The service name, which identifies the PAM stack which is used
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
157 /// to perform authentication.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
158 get = service,
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
159 item = "PAM_SERVICE"
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
160 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
161 trait_item!(
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
162 /// Sets the service name. It's probably a bad idea to change this.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
163 set = set_service,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
164 item = "PAM_SERVICE",
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
165 see = Self::service
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
166 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
167
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
168 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
169 /// The string used to prompt for a user's name.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
170 /// By default, this is a localized version of `login: `.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
171 get = user_prompt,
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
172 item = "PAM_USER_PROMPT"
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
173 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
174 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
175 /// Sets the string used to prompt for a user's name.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
176 set = set_user_prompt,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
177 item = "PAM_USER_PROMPT",
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
178 see = Self::user_prompt
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
179 );
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
180
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
181 trait_item!(
91
039aae9a01f7 Improve documentation on TTY functions.
Paul Fisher <paul@pfish.zone>
parents: 90
diff changeset
182 /// The device path of the TTY being used to log in.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
183 ///
91
039aae9a01f7 Improve documentation on TTY functions.
Paul Fisher <paul@pfish.zone>
parents: 90
diff changeset
184 /// This is the terminal the user is logging in on,
039aae9a01f7 Improve documentation on TTY functions.
Paul Fisher <paul@pfish.zone>
parents: 90
diff changeset
185 /// specified as the full device path (e.g. `/dev/tty0`).
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
186 /// Very old applications may use this instead of `PAM_XDISPLAY`.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
187 get = tty_name,
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
188 item = "PAM_TTY"
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
189 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
190 trait_item!(
91
039aae9a01f7 Improve documentation on TTY functions.
Paul Fisher <paul@pfish.zone>
parents: 90
diff changeset
191 /// Sets the path to the terminal where the user is logging on.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
192 set = set_tty_name,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
193 item = "PAM_TTY",
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
194 see = Self::tty_name
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
195 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
196
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
197 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
198 /// If set, the identity of the remote user logging in.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
199 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
200 /// This is only as trustworthy as the application calling PAM.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
201 get = remote_user,
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
202 item = "PAM_RUSER",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
203 see = Self::remote_host
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
204 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
205 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
206 /// Sets the identity of the remote user logging in.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
207 ///
100
3f11b8d30f63 Implement environment variable management.
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
208 /// This may be set by the application before making calls
3f11b8d30f63 Implement environment variable management.
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
209 /// into a PAM transaction.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
210 set = set_remote_user,
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
211 item = "PAM_RUSER",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
212 see = Self::remote_user
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
213 );
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
214
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
215 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
216 /// If set, the remote location where the user is coming from.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
217 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
218 /// This is only as trustworthy as the application calling PAM.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
219 /// This can be combined with [`Self::remote_user`] to identify
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
220 /// the account the user is attempting to log in from,
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
221 /// with `remote_user@remote_host`.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
222 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
223 /// If unset, "it is unclear where the authentication request
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
224 /// is originating from."
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
225 get = remote_host,
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
226 item = "PAM_RHOST",
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
227 see = Self::remote_user
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
228 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
229 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
230 /// Sets the location where the user is coming from.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
231 ///
100
3f11b8d30f63 Implement environment variable management.
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
232 /// This may be set by the application before making calls
3f11b8d30f63 Implement environment variable management.
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
233 /// into a PAM transaction.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
234 set = set_remote_host,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
235 item = "PAM_RHOST",
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
236 see = Self::remote_host
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
237 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
238
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
239 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
240 /// Gets the user's authentication token (e.g., password).
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
241 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
242 /// This is usually set automatically when
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
243 /// [`authtok`](PamHandleModule::authtok) is called,
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
244 /// but can be manually set.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
245 set = set_authtok_item,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
246 item = "PAM_AUTHTOK",
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
247 see = PamHandleModule::authtok_item
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
248 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
249
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
250 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
251 /// Sets the user's "old authentication token" when changing passwords.
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
252 ///
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
253 /// This is usually set automatically by PAM.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
254 set = set_old_authtok_item,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
255 item = "PAM_OLDAUTHTOK",
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
256 see = PamHandleModule::old_authtok_item
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
257 );
69
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
258 }
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
259
69
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
260 /// Functionality of a PAM handle that can be expected by a PAM application.
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
261 ///
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
262 /// If you are not writing a PAM client application (e.g., you are writing
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
263 /// a module), you should not use the functionality exposed by this trait.
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
264 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
265 /// Like [`PamShared`], this is intended to allow creating mock implementations
69
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
266 /// of PAM for testing PAM applications.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
267 pub trait PamHandleApplication: PamShared {
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
268 /// Starts the authentication process for the user.
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
269 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
270 /// The application calls this to find out who the user is, and verify that
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
271 /// they are really that person. If authentication is successful,
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
272 /// this will return an `Ok(())` [`Result`].
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
273 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
274 /// A PAM module may change the caller's [username](PamShared::username)
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
275 /// as part of the login process, so be sure to check it after making
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
276 /// any PAM application call.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
277 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
278 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
279 #[doc = _linklist!(pam_authenticate: adg, _std)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
280 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
281 #[doc = _guide!(adg: "adg-interface-by-app-expected.html#adg-pam_authenticate")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
282 #[doc = _stdlinks!(3 pam_authenticate)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
283 fn authenticate(&mut self, flags: Flags) -> Result<()>;
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
284
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
285 /// Verifies the validity of the user's account (and other stuff).
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
286 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
287 /// After [authentication](Self::authenticate), an application should call
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
288 /// this to ensure that the user's account is still valid. This may check
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
289 /// for token expiration or that the user's account is not locked.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
290 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
291 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
292 #[doc = _linklist!(pam_acct_mgmt: adg, _std)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
293 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
294 #[doc = _guide!(adg: "adg-interface-by-app-expected.html#adg-pam_acct_mgmt")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
295 #[doc = _stdlinks!(3 pam_acct_mgmt)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
296 fn account_management(&mut self, flags: Flags) -> Result<()>;
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
297
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
298 /// Changes the authentication token.
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
299 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
300 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
301 #[doc = _linklist!(pam_chauthtok: adg, _std)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
302 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
303 #[doc = _guide!(adg: "adg-interface-by-app-expected.html#adg-pam_chauthtok")]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
304 #[doc = _stdlinks!(3 pam_chauthtok)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
305 fn change_authtok(&mut self, flags: Flags) -> Result<()>;
66
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
306 }
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
307
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
308 /// Functionality of a PAM handle that can be expected by a PAM module.
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
309 ///
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
310 /// If you are not writing a PAM module (e.g., you are writing an application),
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
311 /// you should not use any of the functionality exposed by this trait.
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
312 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
313 /// Like [`PamShared`], this is intended to allow creating mock implementations
66
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
314 /// of PAM for testing PAM modules.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
315 pub trait PamHandleModule: Conversation + PamShared {
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
316 /// Retrieves the authentication token from the user.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
317 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
318 /// This should only be used by *authentication* and *password-change*
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
319 /// PAM modules. This is an extension provided by
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
320 /// both Linux-PAM and OpenPAM.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
321 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
322 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
323 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
324 #[doc = _linklist!(pam_get_authtok: man7, manbsd)]
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
325 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
326 /// # Example
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
327 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
328 /// ```no_run
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
329 /// # use nonstick::handle::PamHandleModule;
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
330 /// # fn _doc(handle: &mut impl PamHandleModule) -> Result<(), Box<dyn std::error::Error>> {
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
331 /// // Get the user's password using the default prompt.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
332 /// let pass = handle.authtok(None)?;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
333 /// // Get the user's password using a custom prompt.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
334 /// let pass = handle.authtok(Some("Reveal your secrets!"))?;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
335 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
336 /// # }
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
337 /// ```
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
338 #[doc = _man7!(3 pam_get_authtok)]
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
339 #[doc = _manbsd!(3 pam_get_authtok)]
95
51c9d7e8261a Return owned strings rather than borrowed strings.
Paul Fisher <paul@pfish.zone>
parents: 94
diff changeset
340 fn authtok(&mut self, prompt: Option<&str>) -> Result<String>;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
341
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
342 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
343 /// Gets the user's authentication token (e.g., password).
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
344 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
345 /// This is normally set automatically by PAM when calling
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
346 /// [`authtok`](Self::authtok), but can be set explicitly.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
347 ///
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
348 /// Like `authtok`, this should only ever be called
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
349 /// by *authentication* and *password-change* PAM modules.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
350 get = authtok_item,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
351 item = "PAM_AUTHTOK",
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
352 see = Self::authtok
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
353 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
354
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
355 trait_item!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
356 /// Gets the user's old authentication token when changing passwords.
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
357 ///
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
358 /// This should only ever be called by *password-change* PAM modules.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
359 get = old_authtok_item,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
360 item = "PAM_OLDAUTHTOK",
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
361 see = PamShared::set_old_authtok_item
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
362 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
363
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
364 /*
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
365 TODO: Re-enable this at some point.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
366 /// Gets some pointer, identified by `key`, that has been set previously
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
367 /// using [`set_data`](Self::set_data).
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
368 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
369 /// The data, if present, is still owned by the current PAM session.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
370 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
371 /// See the [`pam_get_data` manual page][man]
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
372 /// or [`pam_get_data` in the Module Writer's Guide][mwg].
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
373 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
374 /// # Safety
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
375 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
376 /// The data stored under the provided key must be of type `T`,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
377 /// otherwise you'll get back a completely invalid `&T`
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
378 /// and further behavior is undefined.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
379 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
380 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_get_data.3.html
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
381 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_get_data
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
382 unsafe fn get_data<T>(&mut self, key: &str) -> Result<Option<&T>>;
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
383
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
384 /// Stores a pointer that can be retrieved later with [`get_data`](Self::get_data).
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
385 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
386 /// This data is accessible to this module and other PAM modules
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
387 /// (using the provided `key`), but is *not* accessible to the application.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
388 /// The PAM session takes ownership of the data, and it will be dropped
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
389 /// when the session ends.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
390 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
391 /// See the [`pam_set_data` manual page][man]
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
392 /// or [`pam_set_data` in the Module Writer's Guide][mwg].
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
393 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
394 /// [man]: https://www.man7.org/linux/man-pages/man3/pam_set_data.3.html
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
395 /// [mwg]: https://www.chiark.greenend.org.uk/doc/libpam-doc/html/mwg-expected-by-module-item.html#mwg-pam_set_data
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
396 fn set_data<T>(&mut self, key: &str, data: Box<T>) -> Result<()>;
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
397 */
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
398 }