Mercurial > crates > nonstick

annotate src/handle.rs @ 159:634cd5f2ac8b

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Separate logging into its own trait apart from the rest of PAM.
author Paul Fisher <paul@pfish.zone>
date Sat, 12 Jul 2025 18:16:18 -0400
parents 0099f2f79f86
children 2f5913131295
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};
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
8 use crate::logging::Logger;
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};
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
10
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
11 /// 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
12 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
13 /// 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
14 /// to both applications and modules.
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
15 ///
144
56b559b7ecea Big rename: separate concepts of Transaction from Handle.
Paul Fisher <paul@pfish.zone>
parents: 143
diff changeset
16 /// 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
17 /// 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
18 /// to test PAM modules and applications.
159
634cd5f2ac8b Separate logging into its own trait apart from the rest of PAM.
Paul Fisher <paul@pfish.zone>
parents: 157
diff changeset
19 pub trait PamShared: Logger {
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
20 /// 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
21 ///
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
22 /// 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
23 /// 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
24 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
25 /// 1. The prompt string passed to this function.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
26 /// 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
27 /// 3. The default prompt, `login: `.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
28 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
29 /// # References
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
30 #[doc = linklist!(pam_get_user: mwg, _std)]
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
31 ///
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
32 /// # Example
19
d654aa0655e5 Making PamHandle a struct with methods
Anthony Nowell <anthony@algorithmia.com>
parents: 15
diff changeset
33 ///
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
34 /// ```no_run
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
35 /// # use nonstick::PamShared;
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
36 /// # 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
37 /// // Get the username using the default prompt.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
38 /// let user = handle.username(None)?;
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
39 /// // Get the username using a custom prompt.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
40 /// // If this were actually called right after the above,
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
41 /// // 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
42 /// 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
43 /// # Ok(())
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
44 /// # }
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
45 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
46 #[doc = stdlinks!(3 pam_get_user)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
47 #[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
48 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
49
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
50 /// 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
51 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
52 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
53 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
54 #[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
55 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
56 #[doc = stdlinks!(3 pam_getenv)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
57 #[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
58 #[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
59 fn environ(&self) -> impl EnvironMap;
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 97
diff changeset
60
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
61 /// 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
62 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
63 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
64 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
65 #[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
66 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
67 #[doc = stdlinks!(3 pam_putenv)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
68 #[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
69 #[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
70 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
71
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
72 /// 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
73 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
74 /// 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
75 /// 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
76 /// by PAM modules only.
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
77 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
78 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
79 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
80 #[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
81 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
82 #[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
83 #[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
84 #[doc = stdlinks!(3 pam_get_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
85 fn items(&self) -> impl Items;
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
86
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
87 /// Read-write access to PAM Items.
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 /// # References
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 = 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
92 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
93 #[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
94 #[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
95 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
96 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
97 }
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 60
diff changeset
98
69
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
99 /// 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
100 ///
8f3ae0c7ab92 Rework conversation data types and make safe wrappers.
Paul Fisher <paul@pfish.zone>
parents: 66
diff changeset
101 /// 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
102 /// 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
103 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
104 /// 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
105 /// 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
106 pub trait Transaction: PamShared {
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
107 /// 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
108 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
109 /// 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
110 /// 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
111 /// this will return an `Ok(())` [`Result`].
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
112 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
113 /// 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
114 /// 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
115 /// any PAM application call.
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
116 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
117 /// # References
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
118 #[doc = linklist!(pam_authenticate: adg, _std)]
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
119 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
120 #[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
121 #[doc = stdlinks!(3 pam_authenticate)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
122 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
123
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
124 /// 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
125 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
126 /// 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
127 /// 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
128 /// 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
129 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
130 /// # References
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
131 #[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
132 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
133 #[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
134 #[doc = stdlinks!(3 pam_acct_mgmt)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
135 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
136
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
137 /// Changes the authentication token.
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
138 ///
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
139 /// # References
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
140 #[doc = linklist!(pam_chauthtok: adg, _std)]
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
141 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
142 #[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
143 #[doc = stdlinks!(3 pam_chauthtok)]
97
efe2f5f8b5b2 Implement "stateless" application-side PAM calls.
Paul Fisher <paul@pfish.zone>
parents: 95
diff changeset
144 fn change_authtok(&mut self, flags: Flags) -> Result<()>;
66
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
145 }
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
146
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
147 /// 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
148 ///
a674799a5cd3 Make `PamHandle` and `PamModuleHandle` traits.
Paul Fisher <paul@pfish.zone>
parents: 64
diff changeset
149 /// 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
150 /// 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
151 ///
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
152 /// 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
153 /// 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
154 pub trait ModuleClient: Conversation + PamShared {
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
155 /// Retrieves the authentication token from the user.
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
156 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
157 /// 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
158 /// PAM modules.
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
159 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
160 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
161 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
162 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
163 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
164 /// # Example
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
165 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
166 /// ```no_run
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
167 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
168 /// # 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
169 /// // Get the user's password using the default prompt.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
170 /// let pass = handle.authtok(None)?;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
171 /// // 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
172 /// 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
173 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
174 /// # }
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
175 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
176 #[doc = man7!(3 pam_get_authtok)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
177 #[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
178 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
179
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
180 /// 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
181 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
182 /// 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
183 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
184 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
185 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
186 #[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
187 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
188 /// # Example
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
189 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
190 /// ```no_run
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
191 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
192 /// # 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
193 /// // 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
194 /// let pass = handle.old_authtok(None)?;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
195 /// // 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
196 /// 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
197 /// Ok(())
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
198 /// # }
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
199 /// ```
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
200 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
201 #[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
202 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
203
153
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
204 /// 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
205 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
206 /// 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
207 /// [`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
208 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
209 /// Data is in a module-specific, type-specific namespace.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
210 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
211 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
212 /// # use nonstick::ModuleClient;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
213 /// # use std::path::PathBuf;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
214 /// # fn test(client: &impl ModuleClient) {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
215 /// // These two can coexist and do not overlap.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
216 /// 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
217 /// 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
218 /// // ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
219 /// 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
220 /// # }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
221 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
222 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
223 /// # References
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
224 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
225 #[doc = linklist!(pam_get_data: mwg, _std)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
226 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
227 #[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
228 #[doc = stdlinks!(3 pam_get_data)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
229
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
230 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
231
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
232 /// Sets module-specific data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
233 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
234 /// 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
235 /// 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
236 /// 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
237 /// 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
238 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
239 /// 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
240 /// 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
241 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
242 /// 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
243 /// below for details on how cleanup is handled.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
244 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
245 /// # Examples
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 /// Each type of data is in a separate namespace:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
248 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
249 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
250 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
251 /// # fn test(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
252 /// client.set_module_data("count", 999i32)?;
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 count_int: Option<&i32> = client.get_module_data("count");
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
255 /// // count_int = Some(&999i32)
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
256 /// 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
257 /// // count_string = None
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
258 /// # Ok(())
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 /// ```
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 /// Data persist across invocations of the same module:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
263 ///
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 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
266 /// // In a pam_authenticate call, this function is called:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
267 /// fn authenticate(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
268 /// client.set_module_data::<u64>("TOKEN_ID", 0x0fa1afe10000beef)?;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
269 /// Ok(())
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
270 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
271 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
272 /// // Later, in a pam_session_start call:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
273 /// fn start_session(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
274 /// match client.get_module_data::<u64>("TOKEN_ID") {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
275 /// Some(&tid) => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
276 /// // This will execute and tid will be 0x0fa1afe10000beef.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
277 /// },
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
278 /// None => { /* This will not execute. */ },
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 /// Ok(())
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 /// ```
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 /// Each module has its own set of data:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
285 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
286 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
287 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
288 /// // 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
289 /// 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
290 /// 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
291 /// Ok(())
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
292 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
293 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
294 /// // 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
295 /// 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
296 /// match client.get_module_data::<String>("value") {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
297 /// Some(value) => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
298 /// // This will match, because pam_module_a's data
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
299 /// // is completely unrelated to pam_module_b's data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
300 /// },
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
301 /// None => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
302 /// // This branch will execute.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
303 /// },
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
304 /// }
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 /// # Ok(())
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
307 /// }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
308 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
309 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
310 /// # Cleanup
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
311 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
312 /// 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
313 /// address space, because PAM applications may `fork()`:
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 /// ```plain
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
316 /// ┃ let tx = start_pam_transaction();
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 /// ┃ tx.authenticate();
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
319 /// ┃ │ // PAM calls into your module where you set data:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
320 /// ┃ │ handle.set_module_data("key", the_data);
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 /// ┃ fork();
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
323 /// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━┓
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
324 /// Parent process Child process
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
325 /// ┃ wait(child); ┃ setuid(user_to_login);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
326 /// ┃ ┆ ┃ // ... do other stuff ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
327 /// ┃ ┆ ┃ drop(tx);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
328 /// ┃ ┆ ┃ │ // PAM cleans up your data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
329 /// ┃ ┆ ┃ │ drop(the_data);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
330 /// ┃ ┆ ┗ exec(user's shell)
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
331 /// ┃ ┆ ┃ // user does stuff over their session
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
332 /// ┃ ┆ ┃ // ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
333 /// ┃ ┆ X
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
334 /// ┃
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
335 /// ┃ drop(tx);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
336 /// ┃ │ // Parent PAM cleans up your data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
337 /// ┃ │ 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
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 /// 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
341 /// we do not (yet) offer this.
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 /// # References
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 #[doc = linklist!(pam_set_data: mwg, _std)]
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 #[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
348 #[doc = stdlinks!(3 pam_set_data)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
349 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
350
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
351 getter!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
352 /// 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
353 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
354 /// 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
355 /// 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
356 ///
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
357 /// 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
358 /// 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
359 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
360 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
361 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
362 #[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
363 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
364 #[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
365 #[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
366 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
367 authtok_item("PAM_AUTHTOK", see = Self::authtok)
72
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
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
370 getter!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
371 /// 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
372 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
373 /// 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
374 /// [`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
375 /// without prompting the user.
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
376 ///
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
377 /// 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
378 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
379 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
380 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
381 #[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
382 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
383 #[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
384 #[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
385 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
386 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
387 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
388 }