Add rustdocs to ssh.rs module (#147)

add rustdocs to ssh module

Author: John15321

libazureinit/src/provision/ssh.rs

@@ -1,6 +1,11 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+//! This module provides functionality for provisioning SSH keys for a user.
+//!
+//! It includes functions to create the necessary `.ssh` directory, set the appropriate
+//! permissions, and write the provided public keys to the `authorized_keys` file.
+
 use std::{
     fs::{self, OpenOptions, Permissions},
     io::{self, Read, Write},
@@ -17,6 +22,7 @@ use tempfile::NamedTempFile;
 use tracing::{error, info, instrument};
 
 lazy_static! {
+    /// A regular expression to match the `PasswordAuthentication` setting in the SSH configuration.
     static ref PASSWORD_REGEX: Regex = Regex::new(
         r"(?m)^\s*#?\s*PasswordAuthentication\s+(yes|no)\s*$"
     )
@@ -25,6 +31,25 @@ lazy_static! {
     );
 }
 
+/// Provisions SSH keys for the specified user.
+///
+/// Creates the `.ssh` directory in the user's home directory, sets the appropriate
+/// permissions, and writes the provided public keys to the `authorized_keys` file.
+///
+/// # Arguments
+///
+/// * `user` - A reference to the user for whom the SSH keys are being provisioned.
+/// * `keys` - A slice of `PublicKeys` to be added to the `authorized_keys` file.
+/// * `authorized_keys_path_string` - An optional string specifying the path to the `authorized_keys` file.
+///
+/// # Returns
+///
+/// This function returns `Result<(), Error>` indicating success or failure.
+///
+/// # Errors
+///
+/// This function will return an error if it fails to create the `.ssh` directory, set permissions,
+/// or write to the `authorized_keys` file.
 #[instrument(skip_all, name = "ssh")]
 pub(crate) fn provision_ssh(
     user: &nix::unistd::User,
@@ -61,6 +86,19 @@ pub(crate) fn provision_ssh(
     Ok(())
 }
 
+/// Retrieves the path to the `authorized_keys` file from the SSH daemon configuration.
+///
+/// Runs the SSH daemon to get the configuration and extracts
+/// the `AuthorizedKeysFile` setting.
+///
+/// # Arguments
+///
+/// * `sshd_config_command_runner` - A function that runs the SSH daemon command and returns its output.
+///
+/// # Returns
+///
+/// This function returns a path to the `authorized_keys` file if found,
+/// or `None` if the setting is not found.
 fn get_authorized_keys_path_from_sshd(
     sshd_config_command_runner: impl Fn() -> io::Result<Output>,
 ) -> Option<String> {
@@ -73,6 +111,15 @@ fn get_authorized_keys_path_from_sshd(
     path
 }
 
+/// Runs the SSH daemon command to get its configuration.
+///
+/// # Arguments
+///
+/// * `sshd_config_command_runner` - A function that runs the SSH daemon command and returns its output.
+///
+/// # Returns
+///
+/// This function returns an output of the command.
 fn run_sshd_command(
     sshd_config_command_runner: impl Fn() -> io::Result<Output>,
 ) -> Option<Output> {
@@ -105,6 +152,19 @@ fn run_sshd_command(
     }
 }
 
+/// Extracts the `AuthorizedKeysFile` path from the SSH daemon configuration output.
+///
+/// Parses the output of the SSH daemon configuration command and extracts the
+/// `AuthorizedKeysFile` setting.
+///
+/// # Arguments
+///
+/// * `sshd_config_output` - A byte slice containing the output of the SSH daemon configuration command.
+///
+/// # Returns
+///
+/// This function returns an `Option<String>` containing the path to the `authorized_keys` file if found,
+/// or `None` if the setting is not found.
 fn extract_authorized_keys_file_path(stdout: &[u8]) -> Option<String> {
     let output = String::from_utf8_lossy(stdout);
     for line in output.lines() {
@@ -124,6 +184,22 @@ fn extract_authorized_keys_file_path(stdout: &[u8]) -> Option<String> {
     None
 }
 
+/// Updates the SSH daemon configuration to ensure `PasswordAuthentication` is set to `yes`.
+///
+/// Checks if the `sshd_config` file exists and updates the `PasswordAuthentication`
+/// setting to `yes`. If the file does not exist, it creates a new one with the appropriate setting.
+///
+/// # Arguments
+///
+/// * `sshd_config_path` - A string slice containing the path to the `sshd_config` file.
+///
+/// # Returns
+///
+/// This function returns `Result<(), io::Error>` indicating success or failure.
+///
+/// # Errors
+///
+/// This function will return an error if it fails to read, write, or create the `sshd_config` file.
 pub(crate) fn update_sshd_config(
     sshd_config_path: &str,
 ) -> Result<(), io::Error> {