From 054c20435aa9e2455f90de9fef57af68916baa14 Mon Sep 17 00:00:00 2001 From: 34n0 <34n0@immerda.ch> Date: Fri, 19 Jan 2024 22:16:29 +0100 Subject: [PATCH] doc: module documentations --- crates/cli/src/cmd/reset.rs | 57 +++++++++++++++++++++++++++++++++++++ crates/cli/src/main.rs | 53 ++++++++++++++++++++++++++++++++++ crates/util/src/config.rs | 35 +++++++++++++++++++++++ crates/util/src/lib.rs | 48 +++++++++++++++++++++++++++++++ crates/util/src/types.rs | 31 ++++++++++++++++++++ 5 files changed, 224 insertions(+) diff --git a/crates/cli/src/cmd/reset.rs b/crates/cli/src/cmd/reset.rs index 92892c7..6a36fd4 100644 --- a/crates/cli/src/cmd/reset.rs +++ b/crates/cli/src/cmd/reset.rs @@ -1,9 +1,49 @@ +//! # Reset Module +//! +//! The `reset` module provides functionality to reset the tally information for a user. +//! It is used in the context of the `sm_authenticate` PAM hook when the `reset` command is specified. +//! The tally information is stored in a file, and this module allows resetting the tally for a specific user. +//! +//! ## License +//! +//! pam-authramp +//! Copyright (C) 2023 github.com/34N0 +//! +//! This program is free software: you can redistribute it and/or modify +//! it under the terms of the GNU General Public License as published by +//! the Free Software Foundation, either version 3 of the License, or +//! (at your option) any later version. +//! +//! This program is distributed in the hope that it will be useful, +//! but WITHOUT ANY WARRANTY; without even the implied warranty of +//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +//! GNU General Public License for more details. +//! +//! You should have received a copy of the GNU General Public License +//! along with this program. If not, see . + use colored::Colorize; use std::{fs, path::PathBuf}; use util::config::Config; use crate::{ArCliError, ArCliInfo, ArCliResult as Acr, ArCliSuccess}; +/// Resets the tally information for a specific user. +/// +/// The function reads the configuration, constructs the path to the tally file for the given user, +/// and attempts to delete the tally file. It returns a result indicating the success or failure of the operation. +/// +/// # Arguments +/// +/// - `user`: The username for which the tally information should be reset. +/// +/// # Returns +/// +/// A `Result` representing the outcome of the operation. +/// +/// - If successful, returns `ArCliResult::Success` with an optional `ArCliSuccess` containing a success message. +/// - If the tally file does not exist, returns `ArCliResult::Info` with an `ArCliInfo` containing an informational message. +/// - If an error occurs during the file deletion, returns `ArCliResult::Error` with an `ArCliError` containing the error message. pub fn user(user: &str) -> Acr { let config = Config::load_file(None); @@ -12,6 +52,23 @@ pub fn user(user: &str) -> Acr { delete_tally(&tally_path, user) } +/// Deletes the tally file for a specific user. +/// +/// The function attempts to remove the tally file specified by the provided path. +/// It returns a result indicating the success or failure of the operation. +/// +/// # Arguments +/// +/// - `path`: The path to the tally file. +/// - `user`: The username associated with the tally file. +/// +/// # Returns +/// +/// A `Result` representing the outcome of the operation. +/// +/// - If successful, returns `ArCliResult::Success` with an optional `ArCliSuccess` containing a success message. +/// - If the tally file does not exist, returns `ArCliResult::Info` with an `ArCliInfo` containing an informational message. +/// - If an error occurs during the file deletion, returns `ArCliResult::Error` with an `ArCliError` containing the error message. fn delete_tally(path: &PathBuf, user: &str) -> Acr { match fs::remove_file(path) { Ok(()) => Acr::Success(Some(ArCliSuccess { diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 8dd0633..a472843 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -1,3 +1,50 @@ +//! # `AuthRamp` CLI Binary +//! +//! The `authramp` CLI binary provides a command-line interface for interacting with the `AuthRamp` PAM module. +//! It includes subcommands to perform various actions, such as resetting a locked PAM user. +//! +//! # Usage +//! +//! To use the `authramp` CLI binary, run it from the command line with the desired subcommand and options. +//! +//! # Example +//! +//! ```bash +//! # Reset a locked PAM user +//! authramp reset --user example_user +//! ``` +//! +//! # Commands +//! +//! - [`reset`](cmd/reset/index.html): Resets a locked PAM user. +//! +//! # Structs +//! +//! - [`ArCliError`](struct.ArCliError.html): Represents an error result in the `AuthRamp` CLI. +//! - [`ArCliSuccess`](struct.ArCliSuccess.html): Represents a success result in the `AuthRamp` CLI. +//! - [`ArCliInfo`](struct.ArCliInfo.html): Represents an informational result in the `AuthRamp` CLI. +//! - [`ArCliResult`](struct.ArCliResult.html): Represents the result of a command execution in the `AuthRamp` CLI. +//! - [`Cli`](struct.Cli.html): Represents the main CLI struct. +//! - [`Command`](enum.Command.html): Represents the available subcommands. +//! +//! ## License +//! +//! pam-authramp +//! Copyright (C) 2023 github.com/34N0 +//! +//! This program is free software: you can redistribute it and/or modify +//! it under the terms of the GNU General Public License as published by +//! the Free Software Foundation, either version 3 of the License, or +//! (at your option) any later version. +//! +//! This program is distributed in the hope that it will be useful, +//! but WITHOUT ANY WARRANTY; without even the implied warranty of +//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +//! GNU General Public License for more details. +//! +//! You should have received a copy of the GNU General Public License +//! along with this program. If not, see . + use clap::{Parser, Subcommand}; use cmd::reset; use colored::Colorize; @@ -87,6 +134,10 @@ enum Command { }, } +/// Main entry point for the `AuthRamp` CLI binary. +/// +/// Initializes the syslog, parses command-line arguments, executes the corresponding subcommand, +/// and prints the result. fn main() { syslog::init_cli_log().unwrap_or_else(|e| println!("{e:?}: Error initializing cli log:")); @@ -95,6 +146,7 @@ fn main() { _ => ArCliResult::Success(None), }; + // Log the result match &cli_res { ArCliResult::Success(res) => { if let Some(res) = res { @@ -107,5 +159,6 @@ fn main() { ArCliResult::Info(_) => (), } + // Print the result println!("{cli_res}"); } diff --git a/crates/util/src/config.rs b/crates/util/src/config.rs index ec2385a..d5d2caa 100644 --- a/crates/util/src/config.rs +++ b/crates/util/src/config.rs @@ -1,3 +1,38 @@ +//! # Configuration Module +//! +//! The `config` module provides functionality for loading and accessing configuration settings +//! used by the `AuthRamp` PAM module and CLI binary. +//! +//! # Usage +//! +//! To use the `config` module, create a `Config` struct using the `load_file` function, providing +//! the path to the configuration file. The `Config` struct allows accessing various configuration +//! settings related to `AuthRamp` behavior. +//! +//! # Structs +//! +//! - [`Config`](struct.Config.html): Represents the configuration settings for `AuthRamp`. +//! +//! ## License +//! +//! pam-authramp +//! Copyright (C) 2023 github.com/34N0 +//! +//! This program is free software: you can redistribute it and/or modify +//! it under the terms of the GNU General Public License as published by +//! the Free Software Foundation, either version 3 of the License, or +//! (at your option) any later version. +//! +//! This program is distributed in the hope that it will be useful, +//! but WITHOUT ANY WARRANTY; without even the implied warranty of +//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +//! GNU General Public License for more details. +//! +//! You should have received a copy of the GNU General Public License +//! along with this program. If not, see . + + + use std::{fs, path::PathBuf}; const DEFAULT_CONFIG_FILE_PATH: &str = "/etc/security/authramp.conf"; diff --git a/crates/util/src/lib.rs b/crates/util/src/lib.rs index 3a948f0..6b324a6 100644 --- a/crates/util/src/lib.rs +++ b/crates/util/src/lib.rs @@ -1,3 +1,51 @@ +//! # `AuthRamp` Utility Crate +//! +//! The `util` crate provides utility modules and functionality used across the `AuthRamp` library, +//! including configuration management, settings handling, syslog initialization, and custom types. +//! +//! # Modules +//! +//! ## `config` +//! +//! The `config` module provides functionality for loading and accessing configuration settings +//! used by the `AuthRamp` PAM module and CLI binary. It includes a `Config` struct that represents +//! the configuration settings for `AuthRamp`. +//! +//! ## `settings` +//! +//! The `settings` module provides functionality for managing and accessing settings used by the +//! `AuthRamp` PAM module. It includes a `Settings` struct that encapsulates configuration settings, +//! user information, and other contextual information required for `AuthRamp`'s operation. +//! +//! ## `syslog` +//! +//! The `syslog` module provides functionality for initializing syslog logging in both the PAM module +//! and the CLI binary. It ensures that log messages are sent to the appropriate syslog facility, +//! making it easy to monitor `AuthRamp` activity. +//! +//! ## `types` +//! +//! The `types` module defines custom types and enumerations used across the `AuthRamp` library. +//! It includes types such as `Actions` and other utility types. +//! +//! ## License +//! +//! pam-authramp +//! Copyright (C) 2023 github.com/34N0 +//! +//! This program is free software: you can redistribute it and/or modify +//! it under the terms of the GNU General Public License as published by +//! the Free Software Foundation, either version 3 of the License, or +//! (at your option) any later version. +//! +//! This program is distributed in the hope that it will be useful, +//! but WITHOUT ANY WARRANTY; without even the implied warranty of +//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +//! GNU General Public License for more details. +//! +//! You should have received a copy of the GNU General Public License +//! along with this program. If not, see . + pub mod config; pub mod settings; pub mod syslog; diff --git a/crates/util/src/types.rs b/crates/util/src/types.rs index 25740b0..6a88d69 100644 --- a/crates/util/src/types.rs +++ b/crates/util/src/types.rs @@ -1,3 +1,34 @@ +//! # Types Module +//! +//! The `types` module defines custom types and enumerations used across the `AuthRamp` library. +//! It includes types such as `Actions` and other utility types. +//! +//! # Usage +//! +//! To use the `types` module, import the necessary types into your code and use them as needed. +//! +//! # Enumerations +//! +//! - [`Actions`](enum.Actions.html): Represents different actions in the `AuthRamp` library. +//! +//! ## License +//! +//! pam-authramp +//! Copyright (C) 2023 github.com/34N0 +//! +//! This program is free software: you can redistribute it and/or modify +//! it under the terms of the GNU General Public License as published by +//! the Free Software Foundation, either version 3 of the License, or +//! (at your option) any later version. +//! +//! This program is distributed in the hope that it will be useful, +//! but WITHOUT ANY WARRANTY; without even the implied warranty of +//! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +//! GNU General Public License for more details. +//! +//! You should have received a copy of the GNU General Public License +//! along with this program. If not, see . + // Action argument defines position in PAM stack #[derive(Debug, Default, Clone, Copy, PartialEq)] pub enum Actions {