Mercurial > crates > nonstick

annotate src/handle.rs @ 157:0099f2f79f86

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Switch logging interface to accept fmt::Arguments. This means that we don't have to format arguments eagerly when logging; an implementation could choose to discard them if it wanted to, avoiding allocations and expensive format calls.
author Paul Fisher <paul@pfish.zone>
date Wed, 09 Jul 2025 16:59:30 -0400
parents 3036f2e6a022
children 634cd5f2ac8b
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
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
3 use crate::_doc::{guide, linklist, man7, manbsd, stdlinks};
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
4 use crate::constants::{Flags, Result};
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
5 use crate::conv::Conversation;
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
6 use crate::environ::{EnvironMap, EnvironMapMut};
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
7 use crate::items::{getter, Items, ItemsMut};
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
8 use crate::logging::{Level, Location};
143
ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul.
Paul Fisher <paul@pfish.zone>
parents: 141
diff changeset
9 use std::ffi::{OsStr, OsString};
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 153
diff changeset
10 use std::fmt;
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
11
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
12 /// 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
13 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
14 /// 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
15 /// to both applications and modules.
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
16 ///
144
56b559b7ecea Big rename: separate concepts of Transaction from Handle.
Paul Fisher <paul@pfish.zone>
parents: 143
diff changeset
17 /// You probably want [`LibPamTransaction`](crate::libpam::LibPamTransaction).
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
18 /// 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
19 /// to test PAM modules and applications.
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
20 pub trait PamShared {
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
21 /// 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
22 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
23 /// 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
24 /// like [`error!`](crate::error!),
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
25 /// [`warn!`](crate::warn!),
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
26 /// [`info!`](crate::info!),
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
27 /// or [`debug!`](crate::debug!).
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
28 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
29 /// 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
30 /// 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
31 /// [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
32 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
33 /// # Example
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
34 ///
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
35 /// ```no_run
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
36 /// # use nonstick::PamShared;
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
37 /// use nonstick::logging::Level;
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
38 /// use nonstick::location;
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
39 /// # 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
40 /// # let delay_ms = 100;
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
41 /// # let url = "https://zombo.com";
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
42 /// // 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
43 /// 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
44 /// 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
45 /// 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
46 /// 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
47 /// // But if you really want to, you can call this yourself:
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 153
diff changeset
48 /// pam_hdl.log(Level::Warn, location!(), format_args!("this is unnecessarily verbose"));
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
49 /// # }
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
50 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
51 #[doc = man7!(3 pam_syslog)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
52 #[doc = manbsd!(3 openpam_log)]
157
0099f2f79f86 Switch logging interface to accept fmt::Arguments.
Paul Fisher <paul@pfish.zone>
parents: 153
diff changeset
53 fn log(&self, level: Level, loc: Location<'_>, entry: fmt::Arguments);
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 91
diff changeset
54
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
55 /// 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
56 ///
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
57 /// 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
58 /// 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
59 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
60 /// 1. The prompt string passed to this function.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
61 /// 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
62 /// 3. The default prompt, `login: `.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
63 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
64 /// # References
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
65 #[doc = linklist!(pam_get_user: mwg, _std)]
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
66 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
67 /// # Example
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
68 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
69 /// ```no_run
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
70 /// # use nonstick::PamShared;
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
71 /// # 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
72 /// // Get the username using the default prompt.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
73 /// let user = handle.username(None)?;
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
74 /// // Get the username using a custom prompt.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
75 /// // If this were actually called right after the above,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
76 /// // both user and user_2 would have the same value.
143
ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul.
Paul Fisher <paul@pfish.zone>
parents: 141
diff changeset
77 /// let user_2 = handle.username(Some("who ARE you even???".as_ref()))?;
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
78 /// # Ok(())
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
79 /// # }
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
80 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
81 #[doc = stdlinks!(3 pam_get_user)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
82 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_user")]
143
ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul.
Paul Fisher <paul@pfish.zone>
parents: 141
diff changeset
83 fn username(&mut self, prompt: Option<&OsStr>) -> Result<OsString>;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
84
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
85 /// The contents of the environment to set for the logged-in user.
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
86 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
87 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
88 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
89 #[doc = linklist!(pam_getenv: adg, mwg, _std)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
90 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
91 #[doc = stdlinks!(3 pam_getenv)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
92 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_getenv")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
93 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#adg-pam_getenv")]
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
94 fn environ(&self) -> impl EnvironMap;
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
95
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
96 /// A writable map of the environment to set for the logged-in user.
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
97 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
98 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
99 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
100 #[doc = linklist!(pam_putenv: adg, mwg, _std)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
101 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
102 #[doc = stdlinks!(3 pam_putenv)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
103 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_putenv")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
104 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#adg-pam_putenv")]
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
105 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
106
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
107 /// Gets Items, data shared by PAM, the application, and modules.
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
108 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
109 /// Certain Items should not be accessed by a PAM application;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
110 /// those are available directly on [`ModuleClient`] for use
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
111 /// by PAM modules only.
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
112 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
113 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
114 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
115 #[doc = linklist!(pam_get_item: mwg, adg, _std)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
116 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
117 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_get_item")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
118 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_item")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
119 #[doc = stdlinks!(3 pam_get_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
120 fn items(&self) -> impl Items;
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
121
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
122 /// Read-write access to PAM Items.
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
123 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
124 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
125 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
126 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
127 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
128 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
129 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
130 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
131 fn items_mut(&mut self) -> impl ItemsMut;
69
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
132 }
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
133
69
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
134 /// 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
135 ///
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
136 /// 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
137 /// 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
138 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
139 /// 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
140 /// of PAM for testing PAM applications.
144
56b559b7ecea Big rename: separate concepts of Transaction from Handle.
Paul Fisher <paul@pfish.zone>
parents: 143
diff changeset
141 pub trait Transaction: PamShared {
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
142 /// 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
143 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
144 /// 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
145 /// 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
146 /// this will return an `Ok(())` [`Result`].
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
147 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
148 /// 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
149 /// 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
150 /// any PAM application call.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
151 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
152 /// # References
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
153 #[doc = linklist!(pam_authenticate: adg, _std)]
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
154 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
155 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_authenticate")]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
156 #[doc = stdlinks!(3 pam_authenticate)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
157 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
158
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
159 /// 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
160 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
161 /// 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
162 /// 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
163 /// 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
164 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
165 /// # References
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
166 #[doc = linklist!(pam_acct_mgmt: adg, _std)]
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
167 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
168 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_acct_mgmt")]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
169 #[doc = stdlinks!(3 pam_acct_mgmt)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
170 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
171
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
172 /// Changes the authentication token.
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
173 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
174 /// # References
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
175 #[doc = linklist!(pam_chauthtok: adg, _std)]
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
176 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
177 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_chauthtok")]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
178 #[doc = stdlinks!(3 pam_chauthtok)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
179 fn change_authtok(&mut self, flags: Flags) -> Result<()>;
66
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
180 }
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
181
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
182 /// 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
183 ///
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
184 /// 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
185 /// 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
186 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
187 /// 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
188 /// of PAM for testing PAM modules.
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
189 pub trait ModuleClient: Conversation + PamShared {
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
190 /// Retrieves the authentication token from the user.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
191 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
192 /// This should only be used by *authentication* and *password-change*
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
193 /// PAM modules.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
194 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
195 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
196 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
197 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
198 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
199 /// # Example
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
200 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
201 /// ```no_run
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
202 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
203 /// # fn _doc(handle: &mut impl ModuleClient) -> Result<(), Box<dyn std::error::Error>> {
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
204 /// // Get the user's password using the default prompt.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
205 /// let pass = handle.authtok(None)?;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
206 /// // Get the user's password using a custom prompt.
143
ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul.
Paul Fisher <paul@pfish.zone>
parents: 141
diff changeset
207 /// let pass = handle.authtok(Some("Reveal your secrets!".as_ref()))?;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
208 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
209 /// # }
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
210 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
211 #[doc = man7!(3 pam_get_authtok)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
212 #[doc = manbsd!(3 pam_get_authtok)]
143
ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul.
Paul Fisher <paul@pfish.zone>
parents: 141
diff changeset
213 fn authtok(&mut self, prompt: Option<&OsStr>) -> Result<OsString>;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
214
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
215 /// Retrieves the user's old authentication token when changing passwords.
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
216 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
217 /// This should only be used by a *password-change* module.
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
218 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
219 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
220 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
221 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
222 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
223 /// # Example
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
224 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
225 /// ```no_run
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
226 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
227 /// # fn _doc(handle: &mut impl ModuleClient) -> Result<(), Box<dyn std::error::Error>> {
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
228 /// // Get the user's password using the default prompt.
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
229 /// let pass = handle.old_authtok(None)?;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
230 /// // Get the user's password using a custom prompt.
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
231 /// let pass = handle.old_authtok(Some("Reveal your secrets!".as_ref()))?;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
232 /// Ok(())
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
233 /// # }
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
234 /// ```
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
235 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
236 #[doc = stdlinks!(3 pam_get_authtok)]
143
ebb71a412b58 Turn everything into OsString and Just Walk Out! for strings with nul.
Paul Fisher <paul@pfish.zone>
parents: 141
diff changeset
237 fn old_authtok(&mut self, prompt: Option<&OsStr>) -> Result<OsString>;
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
238
153
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
239 /// Gets an item of module-specific data stored over the transaction.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
240 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
241 /// This gives you a reference to the data that was earlier set with
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
242 /// [`Self::set_module_data`]. If not present, you get `None`.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
243 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
244 /// Data is in a module-specific, type-specific namespace.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
245 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
246 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
247 /// # use nonstick::ModuleClient;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
248 /// # use std::path::PathBuf;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
249 /// # fn test(client: &impl ModuleClient) {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
250 /// // These two can coexist and do not overlap.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
251 /// let str_data: Option<&String> = client.get_module_data("the_key");
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
252 /// let num_data: Option<&u64> = client.get_module_data("the_key");
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
253 /// // ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
254 /// let nothing_data: Option<&PathBuf> = client.get_module_data("this does not exist");
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
255 /// # }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
256 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
257 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
258 /// # References
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
259 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
260 #[doc = linklist!(pam_get_data: mwg, _std)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
261 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
262 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_get_data")]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
263 #[doc = stdlinks!(3 pam_get_data)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
264
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
265 fn get_module_data<T: 'static>(&self, key: &str) -> Option<&T>;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
266
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
267 /// Sets module-specific data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
268 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
269 /// A PAM module may need to store data across multiple invocations within
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
270 /// the same PAM transaction. For instance, a module that stores credentials
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
271 /// would need to know where those credentials were stored in order to
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
272 /// update or destroy them later. Also see [`Self::get_module_data`].
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
273 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
274 /// Module-specific data gives a module a way to store such data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
275 /// Data are stored in a module-specific, type-specific namespace.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
276 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
277 /// PAM takes ownership of the data passed in. See the **Cleanup** section
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
278 /// below for details on how cleanup is handled.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
279 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
280 /// # Examples
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
281 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
282 /// Each type of data is in a separate namespace:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
283 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
284 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
285 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
286 /// # fn test(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
287 /// client.set_module_data("count", 999i32)?;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
288 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
289 /// let count_int: Option<&i32> = client.get_module_data("count");
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
290 /// // count_int = Some(&999i32)
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
291 /// let count_string: Option<&String> = client.get_module_data("count");
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
292 /// // count_string = None
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
293 /// # Ok(())
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
294 /// # }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
295 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
296 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
297 /// Data persist across invocations of the same module:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
298 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
299 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
300 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
301 /// // In a pam_authenticate call, this function is called:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
302 /// fn authenticate(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
303 /// client.set_module_data::<u64>("TOKEN_ID", 0x0fa1afe10000beef)?;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
304 /// Ok(())
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
305 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
306 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
307 /// // Later, in a pam_session_start call:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
308 /// fn start_session(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
309 /// match client.get_module_data::<u64>("TOKEN_ID") {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
310 /// Some(&tid) => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
311 /// // This will execute and tid will be 0x0fa1afe10000beef.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
312 /// },
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
313 /// None => { /* This will not execute. */ },
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
314 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
315 /// Ok(())
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
316 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
317 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
318 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
319 /// Each module has its own set of data:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
320 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
321 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
322 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
323 /// // This function is called somewhere in pam_module_a.so.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
324 /// fn in_pam_module_a(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
325 /// client.set_module_data("value", String::from("pam_module_a data"))?;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
326 /// Ok(())
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
327 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
328 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
329 /// // This function is called later in pam_module_b.so.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
330 /// fn in_pam_module_b(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
331 /// match client.get_module_data::<String>("value") {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
332 /// Some(value) => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
333 /// // This will match, because pam_module_a's data
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
334 /// // is completely unrelated to pam_module_b's data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
335 /// },
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
336 /// None => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
337 /// // This branch will execute.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
338 /// },
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
339 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
340 /// // ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
341 /// # Ok(())
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
342 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
343 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
344 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
345 /// # Cleanup
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
346 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
347 /// PAM modules should be careful about cleaning up data outside their own
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
348 /// address space, because PAM applications may `fork()`:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
349 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
350 /// ```plain
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
351 /// ┃ let tx = start_pam_transaction();
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
352 /// ┃
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
353 /// ┃ tx.authenticate();
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
354 /// ┃ │ // PAM calls into your module where you set data:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
355 /// ┃ │ handle.set_module_data("key", the_data);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
356 /// ┃
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
357 /// ┃ fork();
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
358 /// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━┓
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
359 /// Parent process Child process
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
360 /// ┃ wait(child); ┃ setuid(user_to_login);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
361 /// ┃ ┆ ┃ // ... do other stuff ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
362 /// ┃ ┆ ┃ drop(tx);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
363 /// ┃ ┆ ┃ │ // PAM cleans up your data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
364 /// ┃ ┆ ┃ │ drop(the_data);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
365 /// ┃ ┆ ┗ exec(user's shell)
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
366 /// ┃ ┆ ┃ // user does stuff over their session
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
367 /// ┃ ┆ ┃ // ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
368 /// ┃ ┆ X
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
369 /// ┃
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
370 /// ┃ drop(tx);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
371 /// ┃ │ // Parent PAM cleans up your data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
372 /// ┃ │ drop(the_data); // Called again, but in this process instead!
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
373 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
374 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
375 /// While LibPAM offers a way to customize the action taken on cleanup,
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
376 /// we do not (yet) offer this.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
377 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
378 /// # References
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
379 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
380 #[doc = linklist!(pam_set_data: mwg, _std)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
381 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
382 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_data")]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
383 #[doc = stdlinks!(3 pam_set_data)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
384 fn set_module_data<T: 'static>(&mut self, key: &str, data: T) -> Result<()>;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
385
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
386 getter!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
387 /// 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
388 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
389 /// This is normally set automatically by PAM through [`Self::authtok`],
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
390 /// but this will get its value (if set) without prompting the user.
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
391 ///
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
392 /// 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
393 /// by *authentication* and *password-change* PAM modules.
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
394 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
395 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
396 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
397 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
398 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
399 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
400 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
401 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
402 authtok_item("PAM_AUTHTOK", see = Self::authtok)
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
403 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
404
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
405 getter!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
406 /// 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
407 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
408 /// This is normally set automatically by PAM through
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
409 /// [`Self::old_authtok`], but this will get its value (if set)
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
410 /// without prompting the user.
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
411 ///
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
412 /// This should only ever be called by *password-change* PAM modules.
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
413 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
414 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
415 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
416 #[doc = linklist!(pam_set_item: mwg, adg, _std)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
417 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
418 #[doc = guide!(adg: "adg-interface-by-app-expected.html#adg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
419 #[doc = guide!(mwg: "mwg-expected-by-module-item.html#mwg-pam_set_item")]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
420 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
421 old_authtok_item("PAM_OLDAUTHTOK", see = ItemsMut::set_old_authtok)
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
422 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
423 }