doc: module documentations

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 <http://www.gnu.org/licenses/>.
+
 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 {

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 <http://www.gnu.org/licenses/>.
+
 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}");
 }

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 <http://www.gnu.org/licenses/>.
+
+
+
 use std::{fs, path::PathBuf};
 
 const DEFAULT_CONFIG_FILE_PATH: &str = "/etc/security/authramp.conf";

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 <http://www.gnu.org/licenses/>.
+
 pub mod config;
 pub mod settings;
 pub mod syslog;

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 <http://www.gnu.org/licenses/>.
+
 // Action argument defines position in PAM stack
 #[derive(Debug, Default, Clone, Copy, PartialEq)]
 pub enum Actions {