Updates documentation

cdhunt · Jan 2, 2024 · 8caed92 · 8caed92
1 parent 0082932
commit 8caed92
Show file tree

Hide file tree

Showing 3 changed files with 47 additions and 14 deletions.
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/docs/Test-SSLCertificate.md b/docs/Test-SSLCertificate.md
@@ -33,18 +33,19 @@ True
 ```
 ### Example 2
 
-Tests an invalid certificates and inspect the `$error` collection for the certificate details.
+Tests an invalid certificates and inspect the error in variable `$validation` for the certificate details.
 
 ```powershell
-Test-SSLCertificate expired.badssl.com
+Test-SSLCertificate expired.badssl.com -ErrorVariable validation
 Test-SSLCertificate: Certificate failed chain validation:
-A certificate chain could not be built to a trusted root authority.
 A required certificate is not within its validity period when verifying against the current system clock or the timestamp in the signed file.
-The revocation function was unable to check revocation for the certificate.
-The revocation function was unable to check revocation because the revocation server was offline.
 False
-PS > $error[0].TargetObject.ChainElements.Certificate.Subject
-CN=badssl-fallback-unknown-subdomain-or-no-sni, O=BadSSL Fallback. Unknown subdomain or no SNI., L=San Francisco, S=California, C=US
+$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

diff --git a/src/public/Test-SSLCertificate.ps1 b/src/public/Test-SSLCertificate.ps1
@@ -31,17 +31,18 @@ function Test-SSLCertificate {
 
     Test the validity of the google SSL Certificate.
 .EXAMPLE
-    PS > Test-SSLCertificate expired.badssl.com
+    Test-SSLCertificate expired.badssl.com -ErrorVariable validation
     Test-SSLCertificate: Certificate failed chain validation:
-    A certificate chain could not be built to a trusted root authority.
     A required certificate is not within its validity period when verifying against the current system clock or the timestamp in the signed file.
-    The revocation function was unable to check revocation for the certificate.
-    The revocation function was unable to check revocation because the revocation server was offline.
     False
-    PS > $error[0].TargetObject.ChainElements.Certificate.Subject
-    CN=badssl-fallback-unknown-subdomain-or-no-sni, O=BadSSL Fallback. Unknown subdomain or no SNI., L=San Francisco, S=California, C=US
+    $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…
 
-    Tests an invalid certificates and inspect the `$error` collection for the certificate details.
+    Tests an invalid certificates and inspect the error in variable `$validation` for the certificate details.
 #>
     [CmdletBinding(DefaultParameterSetName = 'Certificate')]
     param (