crates/nonstick: src/lib.rs annotate

annotate src/lib.rs @ 184:42f747774d94

Really get documentation stuff squared away. Expand READMEs and polish off module documentation.

author	Paul Fisher <paul@pfish.zone>
date	Thu, 31 Jul 2025 14:36:50 -0400
parents	4f46681b3f54
children	b2456d274576

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 //!
184 42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	142 //! # Cargo features
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	143 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	144 //! This crate provides the following Cargo features:
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	145 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	146 //! - link (enabled by default): Actually link against PAM,
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	147 //! rather than just providing an abstract PAM interface.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	148 //! 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	149 //! 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	150 //! - 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	151 //! implementations:
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	152 //! - 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	153 //! This is limited to a few return enums.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	154 //! - 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	155 //! 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	156 //! 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	157 //! - 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	158 //! OpenPAM. This includes enum values.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	159 //! - sun-ext: Enable extensions provided by Sun PAM.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	160 //! This includes enum values.
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	161 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	162 //! # Design
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	163 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	164 //! This library consists of two parts:
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	165 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	166 //! - 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	167 //! 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	168 //! 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	169 //! 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	170 //! 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	171 //! 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	172 //!
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	173 //! - 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	174 //! 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	175 //! for constant-related code).
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	176 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	177 //! # References
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	178 //!
184 42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	179 //! 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	180 //! 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	181 //!
174 9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	182 //! - The Linux-PAM guides provide information for a variety of audiences.
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	183 //! 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	184 //! PAM implementations:
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	185 //! - [Application Developers' Guide][adg]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	186 //! - [Module Writers' Guide][mwg]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	187 //! - [System Administrators' Guide][sag]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	188 //! - PAM framework man page for developers:
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	189 //! - [Linux-PAM developer man page][man7]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	190 //! - [OpenPAM developer man page][manbsd]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	191 //! - [Illumos PAM developer man page][mansun]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	192 //! - PAM framework man page for system administrators:
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	193 //! - [Linux-PAM admin documentation][man7pam8]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	194 //! - [OpenPAM admin documentation][bsdpam8]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	195 //! - [Illumos pam.conf documentation][sunpam5]
9e4ce1631bd3 Dramatically expand documentation. Paul Fisher <paul@pfish.zone> parents: 173 diff changeset	196 //! - [The original PAM specification][spec] (mostly of historical interest)
184 42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	197 //! - [Cooking spray](https://en.wikipedia.org/wiki/Cooking_spray)
176 0730f5f2ee2a Turn `libpam-sys-consts` back into `libpam-sys-impls`. Paul Fisher <paul@pfish.zone> parents: 175 diff changeset	198 #![doc = ""]
184 42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	199 #![doc = _doc::man7!(man7pam8: 8 pam)]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	200 #![doc = _doc::manbsd!(bsdpam8: 8 pam)]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	201 #![doc = _doc::mansun!(sunpam5: 5 "pam.conf")]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	202 #![doc = _doc::stdlinks!(3 pam)]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	203 #![doc = _doc::guide!(adg: "Linux-PAM_ADG.html")]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	204 #![doc = _doc::guide!(mwg: "Linux-PAM_MWG.html")]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	205 #![doc = _doc::guide!(sag: "Linux-PAM_SAG.html")]
42f747774d94 Really get documentation stuff squared away. Paul Fisher <paul@pfish.zone> parents: 183 diff changeset	206 #![doc = _doc::xsso!(spec: "toc.htm")]
15 27730595f1ea Adding pam-http module Anthony Nowell <anthony@algorithmia.com> parents: diff changeset	207
171 e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	208 #[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	209 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	210 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	211 ($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	212 #[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	213 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	214 concat!(
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	215 "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	216 "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	217 $("- ", $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	218 "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	219 " ", 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	220 "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	221 "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	222 "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	223 )
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	224 );
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	225 }
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	226 }
e27c5c667a5a Create full new types for return code and flags, separate end to end. Paul Fisher <paul@pfish.zone> parents: 166 diff changeset	227 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	228 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	229 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	230 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	231 }
72 47eb242a4f88 Fill out the PamHandle trait. Paul Fisher <paul@pfish.zone> parents: 71 diff changeset	232
34 ec70822cbdef Overhaul Andy Caldwell <andrew.caldwell@metaswitch.com> parents: 22 diff changeset	233 pub mod constants;
74 c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	234 pub mod conv;
70 9f8381a1c09c Implement low-level conversation primitives. Paul Fisher <paul@pfish.zone> parents: 69 diff changeset	235 pub mod module;
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	236
73 ac6881304c78 Do conversations, along with way too much stuff. Paul Fisher <paul@pfish.zone> parents: 72 diff changeset	237 pub mod handle;
74 c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	238
106 49d9e2b5c189 An irresponsible mix of implementing libpam-sys and other stuff. Paul Fisher <paul@pfish.zone> parents: 103 diff changeset	239 mod _doc;
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 96 diff changeset	240 mod environ;
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	241 pub mod items;
74 c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	242 #[cfg(feature = "link")]
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	243 pub mod libpam;
92 5ddbcada30f2 Add the ability to log against a PAM handle. Paul Fisher <paul@pfish.zone> parents: 75 diff changeset	244 pub mod logging;
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	245
74 c7c596e6388f Make conversations type-safe (last big reorg) (REAL) (NOT CLICKBAIT) Paul Fisher <paul@pfish.zone> parents: 73 diff changeset	246 #[cfg(feature = "link")]
98 b87100c5eed4 Start on environment variables, and make pointers nicer. Paul Fisher <paul@pfish.zone> parents: 96 diff changeset	247 #[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	248 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	249 #[doc(inline)]
05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	250 pub use crate::{
166 2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	251 constants::{
2f5913131295 Separate flag/action flags into flags and action. Paul Fisher <paul@pfish.zone> parents: 146 diff changeset	252 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	253 },
96 f3e260f9ddcb Make conversation trait use immutable references. Paul Fisher <paul@pfish.zone> parents: 92 diff changeset	254 conv::{BinaryData, Conversation, ConversationAdapter},
100 3f11b8d30f63 Implement environment variable management. Paul Fisher <paul@pfish.zone> parents: 98 diff changeset	255 environ::{EnvironMap, EnvironMapMut},
146 1bc52025156b Split PAM items into their own separate struct. Paul Fisher <paul@pfish.zone> parents: 144 diff changeset	256 handle::{ModuleClient, PamShared, Transaction},
64 bbe84835d6db More organization; add lots of docs. Paul Fisher <paul@pfish.zone> parents: 63 diff changeset	257 module::PamModule,
60 05cc2c27334f The Big Refactor: clean up docs and exports. Paul Fisher <paul@pfish.zone> parents: 57 diff changeset	258 };
176 0730f5f2ee2a Turn `libpam-sys-consts` back into `libpam-sys-impls`. Paul Fisher <paul@pfish.zone> parents: 175 diff changeset	259 use libpam_sys_impls::pam_impl_name;

Mercurial > crates > nonstick

annotate src/lib.rs @ 184:42f747774d94