crates/nonstick: src/lib.rs annotate

annotate src/lib.rs @ 197:705d633e4966 default tip

Added tag libpam-sys/v0.2.0 for changeset 568faf823f34

author	Paul Fisher <paul@pfish.zone>
date	Sun, 03 Aug 2025 01:10:19 -0400
parents	5074d8e00560
children

rev	line source
192 4c39eaa4a5ae Add crate categories to Cargo, and add a little pan in places. Paul Fisher <paul@pfish.zone> parents: 191 diff changeset	1 //! 🍳 A safe, nonstick interface to
4c39eaa4a5ae Add crate categories to Cargo, and add a little pan in places. Paul Fisher <paul@pfish.zone> parents: 191 diff changeset	2 //! the Pluggable Authentication Modules framework.
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	3 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	4 //! Nonstick provides a fully type- and memory-safe interface to
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	5 //! all implementations of PAM, both for PAM modules and PAM applications.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	6 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	7 //! # Usage
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	8 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	9 //! nonstick can be used on either side of a PAM transaction,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	10 //! both to implement an application which calls into PAM,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	11 //! or a module which implements a PAM backend.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	12 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	13 //! 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	14 //! on how to implement a PAM module or application, see the
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	15 //! [References](#references) section.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	16 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	17 //! ## PAM Application
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	18 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	19 //! To implement a PAM application, first implement a [`Conversation`],
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	20 //! then build a [`Transaction`] with the [`TransactionBuilder`].
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	21 //! This can be built into any standard Rust library or binary.
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 //! ```
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	24 //! use nonstick::{
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	25 //! AuthnFlags, Conversation, ConversationAdapter, Result as PamResult, Transaction,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	26 //! TransactionBuilder,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	27 //! };
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	28 //! use std::ffi::{OsStr, OsString};
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	29 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	30 //! /// A basic Conversation that assumes that any "regular" prompt is for
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	31 //! /// the username, and that any "masked" prompt is for the password.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	32 //! ///
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	33 //! /// A typical Conversation will provide the user with an interface
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	34 //! /// 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	35 //! struct UsernamePassConvo {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	36 //! username: String,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	37 //! password: String,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	38 //! }
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	39 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	40 //! // ConversationAdapter is a convenience wrapper for the common case
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	41 //! // of only handling one request at a time.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	42 //! impl ConversationAdapter for UsernamePassConvo {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	43 //! fn prompt(&self, request: impl AsRef<OsStr>) -> PamResult<OsString> {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	44 //! Ok(OsString::from(&self.username))
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 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	47 //! fn masked_prompt(&self, request: impl AsRef<OsStr>) -> PamResult<OsString> {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	48 //! Ok(OsString::from(&self.password))
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 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	51 //! fn error_msg(&self, message: impl AsRef<OsStr>) {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	52 //! // Normally you would want to display this to the user somehow.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	53 //! // In this case, we're just ignoring it.
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 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	56 //! fn info_msg(&self, message: impl AsRef<OsStr>) {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	57 //! // ibid.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	58 //! }
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	59 //! }
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	60 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	61 //! fn authenticate(username: &str, password: &str) -> PamResult<()> {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	62 //! let user_pass = UsernamePassConvo {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	63 //! username: username.into(),
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	64 //! password: password.into(),
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 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	67 //! let mut txn = TransactionBuilder::new_with_service("cortex-sso")
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	68 //! .username(username)
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	69 //! .build(user_pass.into_conversation())?;
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	70 //! // If authentication fails, this will return an error.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	71 //! // We immediately give up rather than re-prompting the user.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	72 //! txn.authenticate(AuthnFlags::empty())?;
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	73 //! txn.account_management(AuthnFlags::empty())?;
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	74 //! Ok(())
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 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	78 //! 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	79 //! 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	80 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	81 //! ## PAM module
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	82 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	83 //! PAM modules are implemented as dynamic libraries loaded into
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	84 //! the address space of the calling application. To implement a module,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	85 //! create a `dylib` crate and implement a [`PamModule`], and export it
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	86 //! using the [`pam_export!`] macro.
193 5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	87 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	88 //! ```toml
193 5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	89 //! # Your Cargo.toml
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	90 //! [package]
193 5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	91 //! name = "samename"
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	92 //! description = "Checks that username and password are the same"
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	93 //! # ...
174 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 //! [lib]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	96 //! crate-type = ["cdylib"]
193 5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	97 //!
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	98 //! [dependencies]
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	99 //! nonstick = "0.1"
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	100 //! # ...
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	101 //! ```
193 5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	102 //!
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	103 //! Once you've set up the dylib crate and added `nonstick` as a dependency,
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	104 //! you can write the code itself:
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	105 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	106 //! ```
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	107 //! // Your lib.rs
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	108 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	109 //! use nonstick::{
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	110 //! pam_export, AuthnFlags, ErrorCode, ModuleClient, PamModule, Result as PamResult,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	111 //! };
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	112 //! use std::ffi::CStr;
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	113 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	114 //! # // This needs to be here to make this doc example work.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	115 //! # fn main() {}
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	116 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	117 //! /// 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	118 //! /// is the same as your password.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	119 //! struct SameName;
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	120 //! pam_export!(SameName);
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 //! impl<M: ModuleClient> PamModule<M> for SameName {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	123 //! fn authenticate(handle: &mut M, _args: Vec<&CStr>, _flags: AuthnFlags) -> PamResult<()> {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	124 //! // Using `None` as the prompt parameter here will tell PAM
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	125 //! // to use the default prompt.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	126 //! let username = handle.username(None)?;
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	127 //! let password = handle.authtok(None)?;
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	128 //! if username == password {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	129 //! Ok(())
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	130 //! } else {
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	131 //! Err(ErrorCode::AuthenticationError)
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	132 //! }
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	133 //! }
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	134 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	135 //! // You can implement other methods of PamModule to provide additional
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	136 //! // features.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	137 //! }
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	138 //! ```
183 4f46681b3f54 Catch a few stray cargo fmt things. Paul Fisher <paul@pfish.zone> parents: 176 diff changeset	139 //!
193 5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	140 //! This gets built into a shared object. By installing this into the PAM
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	141 //! library directory at a place like `pam_samename.so` and configuring PAM
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	142 //! to use it in the authentication stack (beyond the scope of this
5074d8e00560 Doc improvements. Paul Fisher <paul@pfish.zone> parents: 192 diff changeset	143 //! documentation), it will be used to authenticate users.
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	144 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	145 //! # Configuration
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	146 //!
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	147 //! There are a few different PAM implementations available. By default,
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	148 //! nonstick detects which implementation it should use for the current target.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	149 //! 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	150 //! environment variable at build time. See the [`libpam_sys`] documentation.
189 b2456d274576 Add line breaks that rustfmt ate back to documentation. Paul Fisher <paul@pfish.zone> parents: 184 diff changeset	151 #![doc = ""]
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	152 #![doc = concat!("This documentation was built for ", pam_impl_name!(), ".")]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	153 //!
184 42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	154 //! # Cargo features
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	155 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	156 //! This crate provides the following Cargo features:
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	157 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	158 //! - link (enabled by default): Actually link against PAM,
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	159 //! rather than just providing an abstract PAM interface.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	160 //! Enabling this will fail if extensions incompatible with the
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	161 //! PAM implementation you're linking against are also enabled.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	162 //! - Extensions beyond the PAM specification provided by various PAM
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	163 //! implementations:
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	164 //! - basic-ext: Enable extensions provided by both Linux-PAM and OpenPAM.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	165 //! This is limited to a few return enums.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	166 //! - linux-pam-ext (includes basic-ext): Enable extensions provided by
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	167 //! Linux-PAM. This includes enum values and the ability to send
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	168 //! binary messages between the PAM module and the application.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	169 //! - openpam-ext (includes basic-ext): Enable extensions provided by
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	170 //! OpenPAM. This includes enum values.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	171 //! - sun-ext: Enable extensions provided by Sun PAM.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	172 //! This includes enum values.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	173 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	174 //! # Design
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	175 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	176 //! This library consists of two parts:
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	177 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	178 //! - The generic PAM interface, a set of traits describing the behavior of PAM
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	179 //! and the API we export. It is independent of the PAM library itself and
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	180 //! could be implemented by any crate to provide PAM-like services.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	181 //! This is primarily intended to allow a developer to test their PAM modules
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	182 //! and applications by writing mock implementations to verify their
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	183 //! application (or module) code's interactions with PAM itself.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	184 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	185 //! - The bindings to LibPAM itself. This part is included only when link
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	186 //! is enabled. These live in the `libpam` submodule (with a few exceptions
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	187 //! for constant-related code).
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	188 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	189 //! # References
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	190 //!
184 42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	191 //! These documents were used when authoring this library and will probably be
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	192 //! of value if you want to implement a PAM module or a PAM application.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	193 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	194 //! - The Linux-PAM guides provide information for a variety of audiences.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	195 //! 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	196 //! PAM implementations:
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	197 //! - [Application Developers' Guide][adg]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	198 //! - [Module Writers' Guide][mwg]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	199 //! - [System Administrators' Guide][sag]
191 e915c54097d6 Clean up docs and link versions to the right place. Paul Fisher <paul@pfish.zone> parents: 190 diff changeset	200 //! - PAM framework man pages for developers:
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	201 //! - [Linux-PAM developer man page][man7]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	202 //! - [OpenPAM developer man page][manbsd]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	203 //! - [Illumos PAM developer man page][mansun]
191 e915c54097d6 Clean up docs and link versions to the right place. Paul Fisher <paul@pfish.zone> parents: 190 diff changeset	204 //! - PAM framework man pages for system administrators:
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	205 //! - [Linux-PAM admin documentation][man7pam8]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	206 //! - [OpenPAM admin documentation][bsdpam8]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	207 //! - [Illumos pam.conf documentation][sunpam5]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	208 //! - [The original PAM specification][spec] (mostly of historical interest)
191 e915c54097d6 Clean up docs and link versions to the right place. Paul Fisher <paul@pfish.zone> parents: 190 diff changeset	209 //! - [Wikipedia: Cooking spray][spray]
e915c54097d6 Clean up docs and link versions to the right place. Paul Fisher <paul@pfish.zone> parents: 190 diff changeset	210 //!
e915c54097d6 Clean up docs and link versions to the right place. Paul Fisher <paul@pfish.zone> parents: 190 diff changeset	211 //! [spray]: https://en.wikipedia.org/wiki/Cooking_spray
184 42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	212 #![doc = _doc::man7!(man7pam8: 8 pam)]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	213 #![doc = _doc::manbsd!(bsdpam8: 8 pam)]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	214 #![doc = _doc::mansun!(sunpam5: 5 "pam.conf")]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	215 #![doc = _doc::stdlinks!(3 pam)]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	216 #![doc = _doc::guide!(adg: "Linux-PAM_ADG.html")]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	217 #![doc = _doc::guide!(mwg: "Linux-PAM_MWG.html")]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	218 #![doc = _doc::guide!(sag: "Linux-PAM_SAG.html")]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	219 #![doc = _doc::xsso!(spec: "toc.htm")]
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	220
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	221 #[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	222 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	223 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	224 ($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	225 #[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	226 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	227 concat!(
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	228 "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	229 "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	230 $("- ", $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	231 "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	232 " ", 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	233 "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	234 "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	235 "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	236 )
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	237 );
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	238 }
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	239 }
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	240 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	241 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	242 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	243 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	244 }
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	245
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	246 pub mod constants;
74 c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	247 pub mod conv;
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 69 diff changeset	248 pub mod module;
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	249
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	250 pub mod handle;
74 c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	251
106 49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	252 mod _doc;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 96 diff changeset	253 mod environ;
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	254 pub mod items;
74 c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	255 #[cfg(feature = "link")]
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	256 pub mod libpam;
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 75 diff changeset	257 pub mod logging;
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	258
74 c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	259 #[cfg(feature = "link")]
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 96 diff changeset	260 #[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	261 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	262 #[doc(inline)]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	263 pub use crate::{
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	264 constants::{
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	265 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	266 },
96 f3e260f9ddcb Make conversation trait use immutable references. Paul Fisher <paul@pfish.zone> parents: 92 diff changeset	267 conv::{BinaryData, Conversation, ConversationAdapter},
100 3f11b8d30f63 Implement environment variable management. Paul Fisher <paul@pfish.zone> parents: 98 diff changeset	268 environ::{EnvironMap, EnvironMapMut},
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	269 handle::{ModuleClient, PamShared, Transaction},
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 63 diff changeset	270 module::PamModule,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	271 };
190 995aca290452 Restructure the way libpam-sys-impls works to fix cross-compilation. Paul Fisher <paul@pfish.zone> parents: 189 diff changeset	272 #[doc(inline)]
995aca290452 Restructure the way libpam-sys-impls works to fix cross-compilation. Paul Fisher <paul@pfish.zone> parents: 189 diff changeset	273 pub use libpam_sys::pam_impl;
995aca290452 Restructure the way libpam-sys-impls works to fix cross-compilation. Paul Fisher <paul@pfish.zone> parents: 189 diff changeset	274 use libpam_sys::pam_impl_name;

Mercurial > crates > nonstick

annotate src/lib.rs @ 197:705d633e4966 default tip