Adds SSLCertificate commands (#9)

* Adds SSLCertificate commands * Get-SSLCertificate * Show-SSLCertificateUI * Test-SSLCertificate
cdhunt · Jan 2, 2024 · 670fcf1 · 670fcf1
1 parent 8ca3607
commit 670fcf1
Show file tree

Hide file tree

Showing 17 changed files with 609 additions and 208 deletions.
diff --git a/Changelog.md b/Changelog.md
@@ -1,5 +1,9 @@
 # Changelog
 
+## v0.5
+
+- Adds SSLCertificate commands
+
 ## v0.4
 
 - Switch to [Import-ConfigData](https://github.com/cdhunt/Import-ConfigData) for Toml parsing

diff --git a/README.md b/README.md
@@ -56,3 +56,34 @@ Each `[[plan]]` lists:
   [plan.headers]
   Server = "gws"
 ```
+
+### Test-SSLCertificate
+
+The SSLCertificate commands may be moved to a separate module in the future.
+
+- [Get-SSLCertificate](docs/Get-SSLCertificate.md) _Get the SSL Certificate for given host._
+- [Show-SSLCertificateUI](docs/Show-SSLCertificateUI.md) _Displays a dialog box with detailed information about the specified x509 certificate._
+- [Test-SSLCertificate](docs/Test-SSLCertificate.md) _Test the validitiy of a given certificate._
+
+```powershell
+PS > Get-SSLCertificate expired.badssl.com | Test-SSLCertificate -ErrorVariable validation
+False
+```
+
+Validation failures produces an error message.
+
+```text
+Test-SSLCertificate: Certificate failed chain validation:
+A required certificate is not within its validity period when verifying against the current system clock or the timestamp in the signed file.
+```
+
+Inspect the [certificate chain](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509chain) inside the ErrorRecord.
+
+```powershell
+PS > $validation.TargetObject.ChainElements.Certificate
+Thumbprint                                Subject              EnhancedKeyUsageList
+----------                                -------              --------------------
+404BBD2F1F4CC2FDEEF13AABDD523EF61F1C71F3  CN=*.badssl.com, OU… {Server Authentication, Client Authentication}
+339CDD57CFD5B141169B615FF31428782D1DA639  CN=COMODO RSA Domai… {Server Authentication, Client Authentication}
+AFE5D244A8D1194230FF479FE2F897BBCD7A8CB4  CN=COMODO RSA Certi…
+```
diff --git a/build.ps1 b/build.ps1
@@ -176,24 +176,25 @@ function Publish {
 function Docs {
     param ()
 
+    Import-Module C:\source\Build-Docs\publish\Build-Docs\
     Import-Module $publish -Force
 
-    $commands = Get-Command -Module $module -CommandType Function
-    $HelpToMd = [System.IO.Path]::Combine($src, 'internal', 'Export-HelpToMd.ps1')
-    . $HelpToMd
+    $help = Get-HelpModuleData $module
 
-    @("# $module", [System.Environment]::NewLine) | Set-Content -Path "$docs/README.md"
-    $($manifest.Description) | Add-Content -Path "$docs/README.md"
-    @('## Cmdlets', [System.Environment]::NewLine) | Add-Content -Path "$docs/README.md"
+    # docs/README.md
+    $help | New-HelpDoc |
+    Add-ModuleProperty Name -H1 |
+    Add-ModuleProperty Description |
+    Add-HelpDocText "Commands" -H2 |
+    Add-ModuleCommands -AsLinks |
+    Out-HelpDoc -Path 'docs/README.md'
 
-    foreach ($command in $Commands | Sort-Object -Property Verb) {
+    # Individual Commands
+    foreach ($command in $help.Commands) {
         $name = $command.Name
-        $docPath = Join-Path -Path $docs -ChildPath "$name.md"
-        $help = Get-Help -Name $name
-
-        Export-HelpToMd $help | Set-Content -Path $docPath
-
-        "- [$name]($name.md) $($help.Synopsis)" | Add-Content -Path "$docs/README.md"
+        $doc = New-HelpDoc -HelpModuleData $help
+        $doc.Text = $command.ToMD()
+        $doc | Out-HelpDoc -Path "docs/$name.md"
     }
 
     ChangeLog | Set-Content -Path "$parent/Changelog.md"

diff --git a/docs/Get-SSLCertificate.md b/docs/Get-SSLCertificate.md
@@ -0,0 +1,69 @@
+# Get-SSLCertificate
+
+Open an SSL connection to the given host and read the presented server certificate.
+
+## Parameters
+
+### Parameter Set 1
+
+- `[String]` **ComputerName** _A hostname or Url of the server to retreive the certificate._ Mandatory
+- `[Int32]` **Port** _The port to connect to the remote server._ 
+- `[String]` **OutSslStreamVariable** _Stores SslStream connetion details from the command in the specified variable._ 
+
+## Examples
+
+### Example 1
+
+Return the certificate for google.com.
+
+```powershell
+Get-SSLCertificate google.com
+Thumbprint                                Subject              EnhancedKeyUsageList
+----------                                -------              --------------------
+9B97772CC2C860B0D0663AD3ED34272FF927EDEE  CN=*.google.com      Server Authentication
+```
+### Example 2
+
+Verify a server certificate. You can use Test-SSLCertificate to validate the entire certificate chain.
+
+```powershell
+$cert = Get-SSLCertificate expired.badssl.com
+$cert.Verify()
+False
+```
+### Example 3
+
+Write SslStream connection details to Verbose stream.
+
+```powershell
+$cert = Get-SSLCertificate google.com -verbose
+VERBOSE: Converting Uri to host string
+VERBOSE: ComputerName = google.com
+VERBOSE: Cipher: Aes256 strength 256
+VERBOSE: Hash: Sha384 strength 0
+VERBOSE: Key exchange: None strength 0
+VERBOSE: Protocol: Tls13
+```
+### Example 4
+
+Stores SslStream connection details in the `$sslStreamValue` variable.
+
+```powershell
+Get-SSLCertificate -ComputerName 'google.com' -OutSslStreamVariable sslStreamValue
+Thumbprint                                Subject              EnhancedKeyUsageList
+----------                                -------              --------------------
+5D3AD94714B07830A1BFB445F6F581AD0AC77689  CN=*.google.com      Server Authentication
+$sslStreamValue
+CipherAlgorithm      : Aes256
+CipherStrength       : 256
+HashAlgorithm        : Sha384
+HashStrength         : 0
+KeyExchangeAlgorithm : None
+KeyExchangeStrength  : 0
+SslProtocol          : Tls13
+```
+
+## Links
+
+- [Invoke-HttpUnit](Invoke-HttpUnit.md)
+- [Test-SSLCertificate](Test-SSLCertificate.md)
diff --git a/docs/Invoke-HttpUnit.md b/docs/Invoke-HttpUnit.md
@@ -1,40 +1,32 @@
 # Invoke-HttpUnit
 
-
 This is not a 100% accurate port of httpunit. The goal of this module is to utilize Net.Http.HttpClient to more closely simulate a .Net client application. It also provides easy access to the Windows Certificate store for client certificate authentication.
-## Parameters
 
+## Parameters
 
 ### Parameter Set 1
 
-
-- `[String]` **Url** _The URL to retrieve._  Mandatory
-- `[String]` **Code** _For http/https, the expected status code, default 200._  
-- `[String]` **String** _For http/https, a string we expect to find in the result._  
-- `[Hashtable]` **Headers** _For http/https, a hashtable to validate the response headers._  
-- `[TimeSpan]` **Timeout** _A timeout for the test. Default is 3 seconds._  
-- `[X509Certificate]` **Certificate** _For http/https, specifies the client certificate that is used for a secure web request. Enter a variable that contains a certificate._  
-- `[String]` **Method** _For http/https, the HTTP method to send._  
-- `[switch]` **Quiet** _Do not output ErrorRecords for failed tests._  
-
+- `[String]` **Url** _The URL to retrieve._ Mandatory
+- `[String]` **Code** _For http/https, the expected status code, default 200._ 
+- `[String]` **String** _For http/https, a string we expect to find in the result._ 
+- `[Hashtable]` **Headers** _For http/https, a hashtable to validate the response headers._ 
+- `[TimeSpan]` **Timeout** _A timeout for the test. Default is 3 seconds._ 
+- `[X509Certificate]` **Certificate** _For http/https, specifies the client certificate that is used for a secure web request. Enter a variable that contains a certificate._ 
+- `[String]` **Method** _For http/https, the HTTP method to send._ 
+- `[Switch]` **Quiet** _Do not output ErrorRecords for failed tests._ 
 
 ### Parameter Set 2
 
-
-- `[String]` **Path** _Specifies a path to a configuration file with a list of tests. Supported types are .toml, .yml, and .psd1._  Mandatory, ValueFromPipeline
-- `[String[]]` **Tag** _If specified, only runs plans that are tagged with one of the tags specified._  
-- `[switch]` **Quiet** _Do not output ErrorRecords for failed tests._  
-
+- `[String]` **Path** _Specifies a path to a configuration file with a list of tests. Supported types are .toml, .yml, and .psd1._ Mandatory, ValueFromPipeline
+- `[String[]]` **Tag** _If specified, only runs plans that are tagged with one of the tags specified._ 
+- `[Switch]` **Quiet** _Do not output ErrorRecords for failed tests._ 
 
 ## Examples
 
-
 ### Example 1
 
-
 Run an ad-hoc test against one Url.
 
-
 ```powershell
 Invoke-HttpUnit -Url https://www.google.com -Code 200
 Label       : https://www.google.com/
@@ -47,14 +39,10 @@ GotHeaders  : False
 InvalidCert : False
 TimeTotal   : 00:00:00.4695217
 ```
-
-
 ### Example 2
 
-
 Run all of the tests in a given config file.
 
-
 ```powershell
 Invoke-HttpUnit -Path .\example.toml
 Label       : google
@@ -86,9 +74,7 @@ InvalidCert : False
 TimeTotal   : 00:00:00.1021738
 ```
 
-
 ## Links
 
-
 - [https://github.com/StackExchange/httpunit](https://github.com/StackExchange/httpunit)
 - [https://github.com/cdhunt/Import-ConfigData](https://github.com/cdhunt/Import-ConfigData)
diff --git a/docs/README.md b/docs/README.md
@@ -1,8 +1,11 @@
 # httpunitPS
 
-
 A PowerShell port of httpunit.
-## Cmdlets
 
+## Commands
+
+- [Get-SSLCertificate](Get-SSLCertificate.md) _Get the SSL Certificate for given host._
+- [Invoke-HttpUnit](Invoke-HttpUnit.md) _A PowerShell port of httpunit._
+- [Show-SSLCertificateUI](Show-SSLCertificateUI.md) _Displays a dialog box with detailed information about the specified x509 certificate._
+- [Test-SSLCertificate](Test-SSLCertificate.md) _Test the validitiy of a given certificate._
 
-- [Invoke-HttpUnit](Invoke-HttpUnit.md) A PowerShell port of httpunit.
diff --git a/docs/Show-SSLCertificateUI.md b/docs/Show-SSLCertificateUI.md
@@ -0,0 +1,28 @@
+# Show-SSLCertificateUI
+
+Displays a dialog box with detailed information about the specified x509 certificate. The dialog box includes buttons for installing or copying the certificate.
+
+## Parameters
+
+### Parameter Set 1
+
+- `[X509Certificate2]` **Certificate** _An X509Certificate2 certificate object._ Mandatory, ValueFromPipeline
+
+### Parameter Set 2
+
+- `[String]` **ComputerName** _A hostname or Url of the server to retreive the certificate to test._ Mandatory
+- `[Int32]` **Port** _The port to connect to the remote server._ 
+
+## Examples
+
+### Example 1
+
+Launches a certificate dialogue box with details about the google.com certificate.
+
+```powershell
+Get-SSLCertificate google.com | Show-SSLCertificateUI
+```
+
+## Links
+
+- [Get-SSLCertificate](Get-SSLCertificate.md)
diff --git a/docs/Test-SSLCertificate.md b/docs/Test-SSLCertificate.md
@@ -0,0 +1,54 @@
+# Test-SSLCertificate
+
+Verifies the entire certificates chain from a certificate object or hostname.
+
+## Parameters
+
+### Parameter Set 1
+
+- `[X509Certificate2]` **Certificate** _An X509Certificate2 certificate object._ Mandatory, ValueFromPipeline
+- `[Switch]` **RevocationMode** _The Revocation Mode to use in validation.
+NoCheck: No revocation check is performed on the certificate.
+Offline: A revocation check is made using a cached certificate revocation list (CRL).
+Online: A revocation check is made using an online certificate revocation list (CRL)._ 
+
+### Parameter Set 2
+
+- `[Switch]` **RevocationMode** _The Revocation Mode to use in validation.
+NoCheck: No revocation check is performed on the certificate.
+Offline: A revocation check is made using a cached certificate revocation list (CRL).
+Online: A revocation check is made using an online certificate revocation list (CRL)._ 
+- `[String]` **ComputerName** _A hostname or Url of the server to retreive the certificate to test._ Mandatory
+- `[Int32]` **Port** _The port to connect to the remote server._ 
+
+## Examples
+
+### Example 1
+
+Test the validity of the google SSL Certificate.
+
+```powershell
+Get-SSLCertificate google.com | Test-SSLCertificates
+True
+```
+### Example 2
+
+Tests an invalid certificates and inspect the error in variable `$validation` for the certificate details.
+
+```powershell
+Test-SSLCertificate expired.badssl.com -ErrorVariable validation
+Test-SSLCertificate: Certificate failed chain validation:
+A required certificate is not within its validity period when verifying against the current system clock or the timestamp in the signed file.
+False
+$validation.TargetObject.ChainElements.Certificate
+Thumbprint                                Subject              EnhancedKeyUsageList
+----------                                -------              --------------------
+404BBD2F1F4CC2FDEEF13AABDD523EF61F1C71F3  CN=*.badssl.com, OU… {Server Authentication, Client Authentication}
+339CDD57CFD5B141169B615FF31428782D1DA639  CN=COMODO RSA Domai… {Server Authentication, Client Authentication}
+AFE5D244A8D1194230FF479FE2F897BBCD7A8CB4  CN=COMODO RSA Certi…
+```
+
+## Links
+
+- [Get-SSLCertificate](Get-SSLCertificate.md)
+- [https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509chain?view=net-8.0#remarks](https://learn.microsoft.com/en-us/dotnet/api/system.security.cryptography.x509certificates.x509chain?view=net-8.0#remarks)