🌟 [Major]: Introcuding the TLS module (#2)

## Description

This pull request introduces the `TLS` PowerShell module, dedicated to
managing and configuring TLS settings.

### New Functions

- `Get-TLSConfig`: Retrieves the current TLS configuration and lists
available TLS versions.
- `Set-TLSConfig`: Enables specific TLS protocols by updating the
system’s SecurityProtocol settings.

### Documentation

- `README.md`: Now introduces the module as `TLS`, explains its purpose,
and provides detailed examples for retrieving and setting TLS
configurations.
- `Examples`: A new `General.md` example file demonstrates how to use
the module’s functions.

## Type of change

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [ ] 📖 [Docs]
- [ ] 🪲 [Fix]
- [ ] 🩹 [Patch]
- [ ] ⚠️ [Security fix]
- [ ] 🚀 [Feature]
- [x] 🌟 [Breaking change]

## Checklist

<!-- Use the check-boxes [x] on the options that are relevant. -->

- [x] I have performed a self-review of my own code
- [x] I have commented my code, particularly in hard-to-understand areas

Author: MariusStorhaug

README.md

@@ -1,6 +1,6 @@
-# {{ NAME }}
+# TLS
 
-{{ DESCRIPTION }}
+A PowerShell module that helps manage and configure TLS settings on your system.
 
 ## Prerequisites
 
@@ -12,58 +12,81 @@ This uses the following external resources:
 To install the module from the PowerShell Gallery, you can use the following command:
 
 ```powershell
-Install-PSResource -Name {{ NAME }}
-Import-Module -Name {{ NAME }}
+Install-PSResource -Name TLS
+Import-Module -Name TLS
 ```
 
 ## Usage
 
-Here is a list of example that are typical use cases for the module.
+Below are some typical use cases for the module's functions:
 
-### Example 1: Greet an entity
+### Example 1: Retrieve the Current TLS Configuration
 
-Provide examples for typical commands that a user would like to do with the module.
+```powershell
+Get-TLSConfig
+```
+
+- Returns the TLS protocol(s) currently enabled for .NET applications on the system.
+
+### Example 2: List All Available TLS Protocols
+
+```powershell
+Get-TLSConfig -ListAvailable
+```
+
+- Displays all TLS protocol types that can be potentially enabled.
+
+### Example 3: Enable TLS 1.2
 
 ```powershell
-Greet-Entity -Name 'World'
-Hello, World!
+Set-TLSConfig -Protocol Tls12
 ```
 
-### Example 2
+- Enables TLS 1.2 on the system without disabling previously enabled protocols.
 
-Provide examples for typical commands that a user would like to do with the module.
+### Example 4: Enable Multiple TLS Protocols (e.g., TLS 1.2 and TLS 1.3)
 
 ```powershell
-Import-Module -Name PSModuleTemplate
+Set-TLSConfig -Protocol Tls12, Tls13
 ```
 
+- Simultaneously enables TLS 1.2 and TLS 1.3.
+
 ### Find more examples
 
 To find more examples of how to use the module, please refer to the [examples](examples) folder.
 
-Alternatively, you can use the Get-Command -Module 'This module' to find more commands that are available in the module.
-To find examples of each of the commands you can use Get-Help -Examples 'CommandName'.
+Alternatively, you can run:
+```powershell
+Get-Command -Module TLS
+```
+to see all available commands in the module. Then, for any command, you can do:
+```powershell
+Get-Help -Examples <CommandName>
+```
+to view examples specific to that command.
 
 ## Documentation
 
-Link to further documentation if available, or describe where in the repository users can find more detailed documentation about
-the module's functions and features.
+Additional documentation, if available, can be found in this repository. Check out the function-level help by running:
+
+```powershell
+Get-Help Set-TLSConfig -Full
+Get-Help Get-TLSConfig -Full
+```
+
+This will show detailed usage information and parameter descriptions.
 
 ## Contributing
 
 Coder or not, you can contribute to the project! We welcome all contributions.
 
 ### For Users
 
-If you don't code, you still sit on valuable information that can make this project even better. If you experience that the
-product does unexpected things, throw errors or is missing functionality, you can help by submitting bugs and feature requests.
-Please see the issues tab on this project and submit a new issue that matches your needs.
+If you don't code, you still have valuable insights. If you experience any unexpected behavior, see errors, or want additional functionality, please
+submit a bug report or feature request via the Issues tab.
 
 ### For Developers
 
-If you do code, we'd love to have your contributions. Please read the [Contribution guidelines](CONTRIBUTING.md) for more information.
-You can either help by picking up an existing issue or submit a new one if you have an idea for a new feature or improvement.
-
-## Acknowledgements
-
-Here is a list of people and projects that helped this project in some way.
+We’d love your help adding features, fixing bugs, and improving the module. Please read the [Contribution guidelines](CONTRIBUTING.md). You can pick
+up an existing issue or submit a new one if you have ideas for improvements or new features.

examples/General.md

@@ -0,0 +1,43 @@
+# Using Get-TLSConfig and Set-TLSConfig
+
+## Get-TLSConfig
+
+The `Get-TLSConfig` function retrieves the current TLS configuration or lists available TLS versions.
+
+### Example 1: Get Current TLS Configuration
+
+```powershell
+Get-TLSConfig
+```
+
+**Description:** Returns the currently configured TLS version used by .NET applications.
+
+### Example 2: List Available TLS Versions
+
+```powershell
+Get-TLSConfig -ListAvailable
+```
+
+**Description:** Lists all available TLS versions that can be configured.
+
+---
+
+## Set-TLSConfig
+
+The `Set-TLSConfig` function allows enabling one or more TLS protocols by modifying the system's SecurityProtocol settings.
+
+### Example 1: Enable TLS 1.2
+
+```powershell
+Set-TLSConfig -Protocol Tls12
+```
+
+**Description:** Enables TLS 1.2 as a supported security protocol.
+
+### Example 2: Enable TLS 1.2 and TLS 1.3
+
+```powershell
+Set-TLSConfig -Protocol Tls12, Tls13
+```
+
+**Description:** Enables both TLS 1.2 and TLS 1.3 as supported security protocols.

examples/General.ps1

@@ -0,0 +1,36 @@
+function Get-TLSConfig {
+    <#
+        .SYNOPSIS
+        Retrieves the current TLS configuration or lists available TLS versions.
+
+        .DESCRIPTION
+        This function returns the currently configured TLS version used by .NET applications.
+        If the -ListAvailable parameter is specified, it lists all available TLS versions supported.
+
+        .EXAMPLE
+        Get-TLSConfig
+
+        Returns the currently configured TLS version.
+
+        .EXAMPLE
+        Get-TLSConfig -ListAvailable
+
+        Lists all available TLS versions that can be configured.
+
+        .LINK
+        https://psmodule.io/TLS/Functions/Get-TLSConfig/
+    #>
+    [OutputType(ParameterSetName = 'Default', [System.Net.SecurityProtocolType])]
+    [OutputType(ParameterSetName = 'ListAvailable', [Array])]
+    [CmdletBinding(DefaultParameterSetName = 'Default')]
+    param(
+        # List available TLS configurations
+        [Parameter(ParameterSetName = 'ListAvailable')]
+        [switch] $ListAvailable
+    )
+
+    if ($ListAvailable) {
+        return [enum]::GetValues([System.Net.SecurityProtocolType])
+    }
+    return [System.Net.ServicePointManager]::SecurityProtocol
+}

src/functions/public/Get-PSModuleTest.ps1

@@ -0,0 +1,37 @@
+function Set-TLSConfig {
+    <#
+        .SYNOPSIS
+        Configures the system to enable specific TLS protocols.
+
+        .DESCRIPTION
+        The Set-TLSConfig function allows enabling one or more TLS protocols by modifying the system's SecurityProtocol settings.
+        This function updates the current security protocol settings without removing existing ones.
+
+        .EXAMPLE
+        Set-TLSConfig -Protocol Tls12
+
+        Enables TLS 1.2 as a supported security protocol.
+
+        .EXAMPLE
+        Set-TLSConfig -Protocol Tls12, Tls13
+
+        Enables both TLS 1.2 and TLS 1.3 as supported security protocols.
+
+        .LINK
+        https://psmodule.io/TLS/Functions/Set-TLSConfig/
+    #>
+    [OutputType([void])]
+    [CmdletBinding(SupportsShouldProcess)]
+    param(
+        # The TLS protocol to enable
+        [Parameter(Mandatory)]
+        [System.Net.SecurityProtocolType[]] $Protocol
+    )
+
+    foreach ($protocolItem in $Protocol) {
+        Write-Verbose "Enabling $protocolItem"
+        if ($PSCmdlet.ShouldProcess("Security Protocol to [$Protocol]", 'Set')) {
+            [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor $protocolItem
+        }
+    }
+}

src/functions/public/Get-TLSConfig.ps1

@@ -0,0 +1,54 @@
+[Diagnostics.CodeAnalysis.SuppressMessageAttribute(
+    'PSUseDeclaredVarsMoreThanAssignments', '',
+    Justification = 'Pester code blocks'
+)]
+[CmdletBinding()]
+param()
+
+Describe 'TLS' {
+    Context 'Get-TLSConfig' {
+        It 'Should return the current TLS configuration by default' {
+            $result = Get-TLSConfig
+            $expectedTypes = [System.Net.SecurityProtocolType]
+            $result | Should -BeOfType $expectedTypes
+        }
+
+        It 'Should return available TLS versions when -ListAvailable is specified' {
+            $result = Get-TLSConfig -ListAvailable
+            $expectedValues = [enum]::GetValues([System.Net.SecurityProtocolType])
+            $result | Should -Be $expectedValues
+        }
+    }
+
+    Context 'Set-TLSConfig' {
+        BeforeAll {
+            $originalTLS = [System.Net.ServicePointManager]::SecurityProtocol
+        }
+
+        AfterAll {
+            [System.Net.ServicePointManager]::SecurityProtocol = $originalTLS
+        }
+
+        It 'Should enable TLS 1.2 when specified' {
+            Set-TLSConfig -Protocol Tls12
+            $result = [System.Net.ServicePointManager]::SecurityProtocol
+            $result.HasFlag([System.Net.SecurityProtocolType]::Tls12) | Should -BeTrue
+        }
+
+        It 'Should enable multiple TLS versions when specified' {
+            Set-TLSConfig -Protocol Tls12, Tls13
+            $result = [System.Net.ServicePointManager]::SecurityProtocol
+            $result -band [System.Net.SecurityProtocolType]::Tls12 | Should -Be Tls12
+            $result -band [System.Net.SecurityProtocolType]::Tls13 | Should -Be Tls13
+        }
+
+        It 'Should not remove existing TLS settings when adding new ones' {
+            Set-TLSConfig -Protocol Tls11
+            $resultBefore = [System.Net.ServicePointManager]::SecurityProtocol
+            Set-TLSConfig -Protocol Tls12
+            $resultAfter = [System.Net.ServicePointManager]::SecurityProtocol
+            $resultAfter.HasFlag([System.Net.SecurityProtocolType]::Tls11) | Should -BeTrue
+            $resultAfter.HasFlag([System.Net.SecurityProtocolType]::Tls12) | Should -BeTrue
+        }
+    }
+}