licensing and documentation

LICENSE → LICENSE-GPL

@@ -632,7 +632,7 @@ state the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
 
     <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
+    Copyright (C) 2023  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
@@ -652,7 +652,7 @@ Also add information on how to contact you by electronic and paper mail.
   If the program does terminal interaction, make it output a short
 notice like this when it starts in an interactive mode:
 
-    <program>  Copyright (C) <year>  <name of author>
+    pam-authramp  Copyright (C) 2023  34n0
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
     This is free software, and you are welcome to redistribute it
     under certain conditions; type `show c' for details.

LICENSE-MIT

@@ -0,0 +1,8 @@
+Copyright 2023 34n0
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+

crates/cli/src/main.rs

@@ -60,6 +60,13 @@ const BANNER: &str = r"
 ██   ██ ██████    ██   ██   ████   ████   ████      ████
 
 by 34n0@immerda.ch";
+/// Structs and enum to represent CLI output with colored formatting.
+///
+/// `ArCliError`, `ArCliSuccess`, and `ArCliInfo` implement `Display`
+/// to format the message with colors and text.
+///
+/// `ArCliResult` is an enum with variants to hold the different structs.
+/// It implements `Display` to delegate to the inner value's implementation.
 
 #[derive(Debug)]
 pub struct ArCliError {

crates/pam/src/conv.rs

@@ -1,3 +1,23 @@
+//! # PAM conversation module
+//!
+//! This module provides functions for handling PAM conversation.
+//!
+//! The PAM conversation function is a callback provided by the application, which is used
+//! by the PAM library to communicate with the user. This can include prompting for a password,
+//! displaying error messages, or any other interaction with the user.
+//!
+//! The conversation function is provided to the PAM library by the application in the `pam_conv`
+//! structure, which is passed to `pam_start`.
+//!
+//! The `conv` module provides a safe wrapper around the raw `pam_conv` structure, and includes
+//! functions for creating a new `pam_conv` structure, and for invoking the conversation function
+//! with a given message style and message string.
+//!
+//! It also provides the `PamMessageStyle` enum, which represents the different types of messages
+//! that can be passed to the conversation function, and the `PamConv` struct, which represents
+//! a PAM conversation.
+//!
+
 use libc::{c_char, c_int};
 use std::ffi::{CStr, CString};
 use std::ptr;
@@ -37,6 +57,11 @@ pub struct Inner {
 pub struct Conv<'a>(&'a Inner);
 
 impl<'a> Conv<'a> {
+    /// Sends a PAM message to the PAM conversation function.
+    ///
+    /// This allows the PAM module to communicate with the client
+    /// application by sending messages, prompts, errors, etc. that
+    /// will be displayed to the user.
     /// Sends a message to the pam client.
     ///
     /// This will typically result in the user seeing a message or a prompt.
@@ -76,6 +101,9 @@ impl<'a> Conv<'a> {
     }
 }
 
+/// Provides implementations for the `Item` trait for `Conv`.
+/// This allows a `Conv` to be used as an item in the PAM conversation
+/// model.
 impl<'a> Item for Conv<'a> {
     type Raw = Inner;
 

crates/pam/src/items.rs

@@ -1,3 +1,26 @@
+//! # PAM items module
+//!
+//! This module defines the `Item` trait and its associated `ItemType` enum.
+//!
+//! The `Item` trait represents a piece of data (an item) that can be stored in a PAM context.
+//! Each item is identified by its `ItemType`, and can be retrieved from the PAM context using
+//! the `get_item` method, and stored in the PAM context using the `set_item` method.
+//!
+//! The `ItemType` enum represents the different types of items that can be stored in a PAM context.
+//! Each item type corresponds to a specific piece of data, such as the user's username, password,
+//! or the PAM conversation function.
+//!
+//! This module also provides implementations of the `Item` trait for several types, including
+//! `CString`, `Conv`, and `Option<CString>`.
+//!
+//! ## License
+//! 
+//! Copyright 2023 34n0
+//! 
+//! Use of this source code is governed by an MIT-style
+//! license that can be found in the LICENSE file or at
+//! https://opensource.org/licenses/MIT.
+
 #[repr(u32)]
 pub enum ItemType {
     /// The pam_conv structure

crates/pam/src/lib.rs

@@ -1,3 +1,28 @@
+//! # PAM Module
+//!
+//! This is the main module of the PAM library. It provides the main data structures and functions
+//! for interacting with the Pluggable Authentication Modules (PAM) system.
+//!
+//! The main types provided by this module are:
+//! - `PamHandle`: An opaque type that represents a handle to the PAM context. This handle is
+//!   used to make API calls to the PAM system.
+//! - `PamResultCode`: An enum representing the possible result codes that can be returned by
+//!   PAM functions.
+//! - `PamFlag`: An enum representing the possible flags that can be passed to PAM functions.
+//! - `LogLevel`: An enum representing the possible log levels that can be used when logging
+//!   messages with the `pam_syslog` function.
+//!
+//! This module also provides the `PamHooks` trait, which can be implemented by types that
+//! provide hooks for various PAM operations, such as account management and authentication.
+//!
+//!  ## License
+//! 
+//! Copyright 2023 34n0
+//! 
+//! Use of this source code is governed by an MIT-style
+//! license that can be found in the LICENSE file or at
+//! https://opensource.org/licenses/MIT.
+
 pub mod conv;
 pub mod items;
 pub mod macros;
@@ -179,4 +204,4 @@ pub trait PamHooks {
     fn sm_authenticate(pamh: &mut PamHandle, args: Vec<&CStr>, flags: PamFlag) -> PamResultCode {
         PamResultCode::PAM_IGNORE
     }
-}
+}

crates/pam/src/macros.rs

@@ -1,3 +1,25 @@
+//! # PAM macros module
+//!
+//! This module provides useful macros for working with PAM.
+//!
+//! The `pam_hooks!` macro is used to define the hooks that the PAM module provides for
+//! various PAM operations, such as account management (`pam_sm_acct_mgmt`) and
+//! authentication (`pam_sm_authenticate`). The macro takes the name of a struct that
+//! implements the `PamHooks` trait, and generates the necessary extern "C" functions
+//! that the PAM library will call.
+//!
+//! The `pam_try!` macro is a utility macro that simplifies error handling in PAM modules.
+//! It takes a `Result` value, and if the result is `Err`, it immediately returns the error
+//! code. This allows for more concise error handling code.
+//!
+//! ## License
+//! 
+//! Copyright 2023 34n0
+//! 
+//! Use of this source code is governed by an MIT-style
+//! license that can be found in the LICENSE file or at
+//! https://opensource.org/licenses/MIT.
+
 #[macro_export]
 macro_rules! pam_hooks {
     ($ident:ident) => {

integration-test/Makefile

@@ -1,3 +1,9 @@
+# Copyright 2023 34n0
+# 
+# Use of this source code is governed by an MIT-style
+# license that can be found in the LICENSE file or at
+# https://opensource.org/licenses/MIT.
+#
 #
 # 'make'        build executable file 'integration-test'
 # 'make clean'  removes all .o and executable files

integration-test/src/main.c

@@ -1,3 +1,9 @@
+// Copyright 2023 34n0
+// 
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
 #include "tests/tests.h"
 #include <stdio.h>
 

integration-test/src/tests/test-auth-bounce.c

@@ -1,3 +1,9 @@
+// Copyright 2023 34n0
+// 
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
 #include "../utils/utils.h"
 #include <security/_pam_types.h>
 #include <security/pam_appl.h>

integration-test/src/tests/test-invalid-auth.c

@@ -1,3 +1,9 @@
+// Copyright 2023 34n0
+// 
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
 #include "../utils/utils.h"
 #include <security/pam_appl.h>
 #include <security/pam_misc.h>

integration-test/src/tests/test-valid-auth.c

@@ -1,3 +1,9 @@
+// Copyright 2023 34n0
+// 
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
 #include "../utils/utils.h"
 #include <security/pam_appl.h>
 #include <security/pam_misc.h>

integration-test/src/tests/tests.h

@@ -1,3 +1,9 @@
+// Copyright 2023 34n0
+// 
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
 // include/tests.h
 #ifndef TESTS_H
 #define TESTS_H

integration-test/src/utils/utils.c

@@ -1,3 +1,9 @@
+// Copyright 2023 34n0
+// 
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
 #include "utils.h"
 #include <dirent.h>
 #include <security/pam_appl.h>

integration-test/src/utils/utils.h

@@ -1,3 +1,9 @@
+// Copyright 2023 34n0
+// 
+// Use of this source code is governed by an MIT-style
+// license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
 // utils.h
 #ifndef UTILS_H
 #define UTILS_H