Mercurial > crates > nonstick

annotate src/lib.rs @ 183:4f46681b3f54 default tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Catch a few stray cargo fmt things.
author Paul Fisher <paul@pfish.zone>
date Wed, 30 Jul 2025 18:43:07 -0400
parents 0730f5f2ee2a
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
1 //! A safe, nonstick interface to the Pluggable Authentication Module framework.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
2 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
3 //! Nonstick provides a fully type- and memory-safe interface to
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
4 //! all implementations of PAM, both for PAM modules and PAM applications.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
5 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
6 //! # Usage
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
7 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
8 //! nonstick can be used on either side of a PAM transaction,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
9 //! both to implement an application which calls into PAM,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
10 //! or a module which implements a PAM backend.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
11 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
12 //! For more information about how PAM works in general, or more pointers
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
13 //! on how to implement a PAM module or application, see the
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
14 //! [References](#references) section.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
15 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
16 //! ## PAM Application
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
17 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
18 //! To implement a PAM application, first implement a [`Conversation`],
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
19 //! then build a [`Transaction`] with the [`TransactionBuilder`].
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
20 //! This can be built into any standard Rust library or binary.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
21 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
22 //! ```
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
23 //! use nonstick::{
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
24 //! AuthnFlags, Conversation, ConversationAdapter, Result as PamResult, Transaction,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
25 //! TransactionBuilder,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
26 //! };
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
27 //! use std::ffi::{OsStr, OsString};
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
28 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
29 //! /// A basic Conversation that assumes that any "regular" prompt is for
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
30 //! /// the username, and that any "masked" prompt is for the password.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
31 //! ///
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
32 //! /// A typical Conversation will provide the user with an interface
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
33 //! /// to interact with PAM, e.g. a dialogue box or a terminal prompt.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
34 //! struct UsernamePassConvo {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
35 //! username: String,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
36 //! password: String,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
37 //! }
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
38 //!
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
39 //! // ConversationAdapter is a convenience wrapper for the common case
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
40 //! // of only handling one request at a time.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
41 //! impl ConversationAdapter for UsernamePassConvo {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
42 //! fn prompt(&self, request: impl AsRef<OsStr>) -> PamResult<OsString> {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
43 //! Ok(OsString::from(&self.username))
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
44 //! }
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
45 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
46 //! fn masked_prompt(&self, request: impl AsRef<OsStr>) -> PamResult<OsString> {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
47 //! Ok(OsString::from(&self.password))
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
48 //! }
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
49 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
50 //! fn error_msg(&self, message: impl AsRef<OsStr>) {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
51 //! // Normally you would want to display this to the user somehow.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
52 //! // In this case, we're just ignoring it.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
53 //! }
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
54 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
55 //! fn info_msg(&self, message: impl AsRef<OsStr>) {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
56 //! // ibid.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
57 //! }
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
58 //! }
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
59 //!
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
60 //! fn authenticate(username: &str, password: &str) -> PamResult<()> {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
61 //! let user_pass = UsernamePassConvo {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
62 //! username: username.into(),
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
63 //! password: password.into(),
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
64 //! };
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
65 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
66 //! let mut txn = TransactionBuilder::new_with_service("cortex-sso")
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
67 //! .username(username)
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
68 //! .build(user_pass.into_conversation())?;
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
69 //! // If authentication fails, this will return an error.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
70 //! // We immediately give up rather than re-prompting the user.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
71 //! txn.authenticate(AuthnFlags::empty())?;
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
72 //! txn.account_management(AuthnFlags::empty())?;
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
73 //! Ok(())
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
74 //! }
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
75 //! ```
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
76 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
77 //! PAM just tells you that the user is, in fact, who they say they are.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
78 //! It is up to your application to choose what to do with that information.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
79 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
80 //! ## PAM module
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
81 //!
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
82 //! PAM modules are implemented as dynamic libraries loaded into
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
83 //! the address space of the calling application. To implement a module,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
84 //! create a `dylib` crate and implement a [`PamModule`], and export it
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
85 //! using the [`pam_export!`] macro.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
86 //! ```toml
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
87 //! ## Your Cargo.toml
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
88 //! [package]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
89 //! name = "example-package"
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
90 //! ## ...
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
91 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
92 //! [lib]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
93 //! crate-type = ["cdylib"]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
94 //! ```
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
95 //! ```
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
96 //! // Your lib.rs
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
97 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
98 //! use nonstick::{
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
99 //! pam_export, AuthnFlags, ErrorCode, ModuleClient, PamModule, Result as PamResult,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
100 //! };
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
101 //! use std::ffi::CStr;
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
102 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
103 //! # // This needs to be here to make this doc example work.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
104 //! # fn main() {}
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
105 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
106 //! /// A module that only allows you to log in if your username
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
107 //! /// is the same as your password.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
108 //! struct SameName;
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
109 //! pam_export!(SameName);
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
110 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
111 //! impl<M: ModuleClient> PamModule<M> for SameName {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
112 //! fn authenticate(handle: &mut M, _args: Vec<&CStr>, _flags: AuthnFlags) -> PamResult<()> {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
113 //! // Using `None` as the prompt parameter here will tell PAM
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
114 //! // to use the default prompt.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
115 //! let username = handle.username(None)?;
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
116 //! let password = handle.authtok(None)?;
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
117 //! if username == password {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
118 //! Ok(())
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
119 //! } else {
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
120 //! Err(ErrorCode::AuthenticationError)
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
121 //! }
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
122 //! }
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
123 //!
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
124 //! // You can implement other methods of PamModule to provide additional
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
125 //! // features.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
126 //! }
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
127 //! ```
183
4f46681b3f54 Catch a few stray cargo fmt things.
Paul Fisher <paul@pfish.zone>
parents: 176
diff changeset
128 //!
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
129 //! This gets built into a library like `pam_samename.so`. By installing this
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
130 //! into your PAM library directory and configuring PAM to use it in
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
131 //! the authentication stack (beyond the scope of this documentation), it will
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
132 //! be used to authenticate users.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
133 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
134 //! # Configuration
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
135 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
136 //! There are a few different PAM implementations available. By default,
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
137 //! nonstick detects which implementation it should use for the current target.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
138 //! If you need to choose a different implementation, set the `LIBPAMSYS_IMPL`
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
139 //! environment variable at build time. See the [`libpam_sys`] documentation.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
140 #![doc = concat!("This documentation was built for **", pam_impl_name!(), "**.")]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
141 //!
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
142 //! # References
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
143 //!
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
144 //! - The Linux-PAM guides provide information for a variety of audiences.
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
145 //! While some of it is specific to Linux-PAM, much of it applies to other
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
146 //! PAM implementations:
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
147 //! - [Application Developers' Guide][adg]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
148 //! - [Module Writers' Guide][mwg]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
149 //! - [System Administrators' Guide][sag]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
150 //! - PAM framework man page for developers:
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
151 //! - [Linux-PAM developer man page][man7]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
152 //! - [OpenPAM developer man page][manbsd]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
153 //! - [Illumos PAM developer man page][mansun]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
154 //! - PAM framework man page for system administrators:
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
155 //! - [Linux-PAM admin documentation][man7pam8]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
156 //! - [OpenPAM admin documentation][bsdpam8]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
157 //! - [Illumos pam.conf documentation][sunpam5]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
158 //! - [The original PAM specification][spec] (mostly of historical interest)
176
0730f5f2ee2a Turn `libpam-sys-consts` back into `libpam-sys-impls`.
Paul Fisher <paul@pfish.zone>
parents: 175
diff changeset
159 #![doc = ""]
174
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
160 #![doc = crate::_doc::man7!(man7pam8: 8 pam)]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
161 #![doc = crate::_doc::manbsd!(bsdpam8: 8 pam)]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
162 #![doc = crate::_doc::mansun!(sunpam5: 5 "pam.conf")]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
163 #![doc = crate::_doc::stdlinks!(3 pam)]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
164 #![doc = crate::_doc::guide!(adg: "Linux-PAM_ADG.html")]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
165 #![doc = crate::_doc::guide!(mwg: "Linux-PAM_MWG.html")]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
166 #![doc = crate::_doc::guide!(sag: "Linux-PAM_SAG.html")]
9e4ce1631bd3 Dramatically expand documentation.
Paul Fisher <paul@pfish.zone>
parents: 173
diff changeset
167 #![doc = crate::_doc::xsso!(spec: "toc.htm")]
15
27730595f1ea Adding pam-http module
Anthony Nowell <anthony@algorithmia.com>
parents:
diff changeset
168
171
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
169 #[cfg(feature = "link")]
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
170 mod _compat_checker {
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
171 macro_rules! feature_check {
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
172 ($feature:literal, pam_impl = ($($pimpl:literal),*)) => {
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
173 #[cfg(all(feature = $feature, not(any($(pam_impl = $pimpl),*))))]
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
174 compile_error!(
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
175 concat!(
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
176 "The feature '", $feature, "' is only available ",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
177 "with these PAM implementations:\n",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
178 $("- ", $pimpl, "\n"),*,
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
179 "The current PAM implementation is:\n\n",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
180 " ", libpam_sys::pam_impl_name!(), "\n\n",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
181 "Set the 'LIBPAMSYS_IMPL' environment variable to one of ",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
182 "the above PAM implementation names to build ",
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
183 "for that implementation of PAM."
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
184 )
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
185 );
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
186 }
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
187 }
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
188 feature_check!("linux-pam-ext", pam_impl = ("LinuxPam"));
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
189 feature_check!("basic-ext", pam_impl = ("LinuxPam", "OpenPam"));
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
190 feature_check!("openpam-ext", pam_impl = ("OpenPam"));
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
191 feature_check!("sun-ext", pam_impl = ("Sun"));
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
192 }
72
47eb242a4f88 Fill out the PamHandle trait.
Paul Fisher <paul@pfish.zone>
parents: 71
diff changeset
193
34
ec70822cbdef Overhaul
Andy Caldwell <andrew.caldwell@metaswitch.com>
parents: 22
diff changeset
194 pub mod constants;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
195 pub mod conv;
70
9f8381a1c09c Implement low-level conversation primitives.
Paul Fisher <paul@pfish.zone>
parents: 69
diff changeset
196 pub mod module;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
197
73
ac6881304c78 Do conversations, along with way too much stuff.
Paul Fisher <paul@pfish.zone>
parents: 72
diff changeset
198 pub mod handle;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
199
106
49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff.
Paul Fisher <paul@pfish.zone>
parents: 103
diff changeset
200 mod _doc;
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 96
diff changeset
201 mod environ;
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
202 pub mod items;
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
203 #[cfg(feature = "link")]
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
204 pub mod libpam;
92
5ddbcada30f2 Add the ability to log against a PAM handle.
Paul Fisher <paul@pfish.zone>
parents: 75
diff changeset
205 pub mod logging;
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
206
74
c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT)
Paul Fisher <paul@pfish.zone>
parents: 73
diff changeset
207 #[cfg(feature = "link")]
98
b87100c5eed4 Start on environment variables, and make pointers nicer.
Paul Fisher <paul@pfish.zone>
parents: 96
diff changeset
208 #[doc(inline)]
171
e27c5c667a5a Create full new types for return code and flags, separate end to end.
Paul Fisher <paul@pfish.zone>
parents: 166
diff changeset
209 pub use crate::libpam::{LibPamHandle, LibPamTransaction, TransactionBuilder};
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
210 #[doc(inline)]
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
211 pub use crate::{
166
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
212 constants::{
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
213 AuthnFlags, AuthtokAction, AuthtokFlags, BaseFlags, CredAction, ErrorCode, Result,
2f5913131295 Separate flag/action flags into flags and action.
Paul Fisher <paul@pfish.zone>
parents: 146
diff changeset
214 },
96
f3e260f9ddcb Make conversation trait use immutable references.
Paul Fisher <paul@pfish.zone>
parents: 92
diff changeset
215 conv::{BinaryData, Conversation, ConversationAdapter},
100
3f11b8d30f63 Implement environment variable management.
Paul Fisher <paul@pfish.zone>
parents: 98
diff changeset
216 environ::{EnvironMap, EnvironMapMut},
146
1bc52025156b Split PAM items into their own separate struct.
Paul Fisher <paul@pfish.zone>
parents: 144
diff changeset
217 handle::{ModuleClient, PamShared, Transaction},
64
bbe84835d6db More organization; add lots of docs.
Paul Fisher <paul@pfish.zone>
parents: 63
diff changeset
218 module::PamModule,
60
05cc2c27334f The Big Refactor: clean up docs and exports.
Paul Fisher <paul@pfish.zone>
parents: 57
diff changeset
219 };
176
0730f5f2ee2a Turn `libpam-sys-consts` back into `libpam-sys-impls`.
Paul Fisher <paul@pfish.zone>
parents: 175
diff changeset
220 use libpam_sys_impls::pam_impl_name;