Mercurial > crates > nonstick

annotate src/handle.rs @ 169:77470e45e397

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Set up stuff to work the way Sun expects it to. This sets up PAM to use pam_authtok_get.so on Sun machines.
author Paul Fisher <paul@pfish.zone>
date Tue, 15 Jul 2025 01:32:21 -0400
parents 2f5913131295
children e27c5c667a5a
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};
166
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 159
diff changeset
4 use crate::constants::{AuthnFlags, AuthtokFlags, 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)]
166
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 159
diff changeset
122 fn authenticate(&mut self, flags: AuthnFlags) -> 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)]
166
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 159
diff changeset
135 fn account_management(&mut self, flags: AuthnFlags) -> 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)]
166
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 159
diff changeset
144 fn change_authtok(&mut self, flags: AuthtokFlags) -> 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 ///
169
77470e45e397 Set up stuff to work the way Sun expects it to.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
160 /// With Sun's PAM implementation, this works a little bit differently
77470e45e397 Set up stuff to work the way Sun expects it to.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
161 /// than it does everywhere else. Sun's PAM provides for password input
77470e45e397 Set up stuff to work the way Sun expects it to.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
162 /// *exclusively* though module stacking with the
77470e45e397 Set up stuff to work the way Sun expects it to.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
163 /// [`pam_authtok_get` module][pam_authtok_get]. On Sun, this function
77470e45e397 Set up stuff to work the way Sun expects it to.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
164 /// is exactly equivalent to [`Self::authtok_item`], in that it only
77470e45e397 Set up stuff to work the way Sun expects it to.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
165 /// retrieves the existing item.
77470e45e397 Set up stuff to work the way Sun expects it to.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
166 ///
103
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
167 /// # References
dfcd96a74ac4 write a truly prodigious amount of documentation
Paul Fisher <paul@pfish.zone>
parents: 100
diff changeset
168 ///
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
169 #[doc = linklist!(pam_get_authtok: man7, manbsd)]
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
170 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
171 /// # Example
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
172 ///
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
173 /// ```no_run
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
174 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
175 /// # 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
176 /// // Get the user's password using the default prompt.
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
177 /// let pass = handle.authtok(None)?;
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
178 /// // 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
179 /// 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
180 /// Ok(())
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
181 /// # }
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
182 /// ```
116
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
183 #[doc = man7!(3 pam_get_authtok)]
a12706e42c9d Logging, macros, and building:
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
184 #[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
185 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
186
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
187 /// 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
188 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
189 /// 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
190 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
191 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
192 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
193 #[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
194 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
195 /// # Example
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
196 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
197 /// ```no_run
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
198 /// # use nonstick::handle::ModuleClient;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
199 /// # 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
200 /// // 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
201 /// let pass = handle.old_authtok(None)?;
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
202 /// // 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
203 /// 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
204 /// Ok(())
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
205 /// # }
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
206 /// ```
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
207 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
208 #[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
209 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
210
153
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
211 /// 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
212 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
213 /// 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
214 /// [`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
215 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
216 /// Data is in a module-specific, type-specific namespace.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
217 ///
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 /// # use nonstick::ModuleClient;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
220 /// # use std::path::PathBuf;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
221 /// # fn test(client: &impl ModuleClient) {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
222 /// // These two can coexist and do not overlap.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
223 /// 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
224 /// 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
225 /// // ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
226 /// 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
227 /// # }
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
228 /// ```
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 /// # References
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 #[doc = linklist!(pam_get_data: mwg, _std)]
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 #[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
235 #[doc = stdlinks!(3 pam_get_data)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
236
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
237 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
238
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
239 /// Sets module-specific data.
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 /// 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
242 /// 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
243 /// 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
244 /// 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
245 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
246 /// 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
247 /// 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
248 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
249 /// 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
250 /// below for details on how cleanup is handled.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
251 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
252 /// # Examples
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 /// Each type of data is in a separate namespace:
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 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
258 /// # fn test(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
259 /// client.set_module_data("count", 999i32)?;
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 /// 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
262 /// // count_int = Some(&999i32)
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
263 /// 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
264 /// // count_string = None
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
265 /// # Ok(())
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 /// ```
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 /// Data persist across invocations of the same module:
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 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
273 /// // In a pam_authenticate call, this function is called:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
274 /// fn authenticate(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
275 /// client.set_module_data::<u64>("TOKEN_ID", 0x0fa1afe10000beef)?;
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
276 /// Ok(())
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 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
279 /// // Later, in a pam_session_start call:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
280 /// fn start_session(client: &mut impl ModuleClient) -> Result<()> {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
281 /// match client.get_module_data::<u64>("TOKEN_ID") {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
282 /// Some(&tid) => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
283 /// // This will execute and tid will be 0x0fa1afe10000beef.
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 /// None => { /* This will not execute. */ },
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 /// Ok(())
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 /// ```
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
290 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
291 /// Each module has its own set of data:
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 /// # use nonstick::{ModuleClient, Result};
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
295 /// // 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
296 /// 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
297 /// 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
298 /// Ok(())
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 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
301 /// // 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
302 /// 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
303 /// match client.get_module_data::<String>("value") {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
304 /// Some(value) => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
305 /// // This will match, because pam_module_a's data
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
306 /// // is completely unrelated to pam_module_b's data.
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 /// None => {
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
309 /// // This branch will execute.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
310 /// },
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 /// // ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
313 /// # Ok(())
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 /// ```
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 /// # Cleanup
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 /// 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
320 /// address space, because PAM applications may `fork()`:
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 /// ```plain
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
323 /// ┃ let tx = start_pam_transaction();
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
324 /// ┃
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
325 /// ┃ tx.authenticate();
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
326 /// ┃ │ // PAM calls into your module where you set data:
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
327 /// ┃ │ handle.set_module_data("key", the_data);
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 /// ┃ fork();
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
330 /// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━┓
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
331 /// Parent process Child process
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
332 /// ┃ wait(child); ┃ setuid(user_to_login);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
333 /// ┃ ┆ ┃ // ... do other stuff ...
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
334 /// ┃ ┆ ┃ drop(tx);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
335 /// ┃ ┆ ┃ │ // PAM cleans up your data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
336 /// ┃ ┆ ┃ │ drop(the_data);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
337 /// ┃ ┆ ┗ exec(user's shell)
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
338 /// ┃ ┆ ┃ // user does stuff over their session
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 /// ┃ ┆ X
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
341 /// ┃
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
342 /// ┃ drop(tx);
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
343 /// ┃ │ // Parent PAM cleans up your data.
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
344 /// ┃ │ 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
345 /// ```
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 /// 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
348 /// we do not (yet) offer this.
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 /// # References
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
351 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
352 #[doc = linklist!(pam_set_data: mwg, _std)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
353 ///
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
354 #[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
355 #[doc = stdlinks!(3 pam_set_data)]
3036f2e6a022 Add module-specific data support.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
356 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
357
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
358 getter!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
359 /// 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
360 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
361 /// 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
362 /// 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
363 ///
90
f6186e41399b Miscellaneous fixes and cleanup:
Paul Fisher <paul@pfish.zone>
parents: 80
diff changeset
364 /// 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
365 /// 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
366 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
367 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
368 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
369 #[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
370 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
371 #[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
372 #[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
373 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
374 authtok_item("PAM_AUTHTOK", see = Self::authtok)
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
375 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
376
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
377 getter!(
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
378 /// 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
379 ///
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
380 /// 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
381 /// [`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
382 /// without prompting the user.
141
a508a69c068a Remove a lot of Results from functions.
Paul Fisher <paul@pfish.zone>
parents: 116
diff changeset
383 ///
80
5aa1a010f1e8 Start using PAM headers; improve owned/borrowed distinction.
Paul Fisher <paul@pfish.zone>
parents: 78
diff changeset
384 /// 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
385 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
386 /// # References
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
387 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
388 #[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
389 ///
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
390 #[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
391 #[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
392 #[doc = stdlinks!(3 pam_set_item)]
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
393 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
394 );
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
395 }