Fix DN (BaseDN) parameter docstrings

In X.500 parlance, a _Distinguished Name_ (_DN_) is a fully-qualified object path<sup>[1][1],[2][2]</sup> For example, `CN=example.com, O=IANA, C=US` is a DN. Prior to this, however, the `DN` parameter did not specify the fully-qualified DN, but instead only the path part, minus the _Common Name_. In the above example, that would be `O=IANA, C=US`, were the common name is `CN=example.com`. This path part is properly known as the _Base DN_.<sup>[2][2],[3][3]</sup> Therefore, this commit updates the documentation for the `DN` parameter with the appropriate names. Fixes dsccommunity#89 [1]: https://ldapwiki.com/wiki/Distinguished%20Names [2]: https://www.novell.com/documentation/extend5/Docs/help/Composer/books/LDAPGlossary.html [3]: https://ldapwiki.com/wiki/BaseDN
lamawithonel · Sep 30, 2021 · 4c61828 · 4c61828
1 parent 8ab2a1d
commit 4c61828
Show file tree

Hide file tree

Showing 5 changed files with 23 additions and 23 deletions.
diff --git a/source/DSCResources/DSC_WSManListener/DSC_WSManListener.psm1 b/source/DSCResources/DSC_WSManListener/DSC_WSManListener.psm1
@@ -133,8 +133,8 @@ function Get-TargetResource
         Listener if a thumbprint is not specified.
 
     .PARAMETER DN
-        This is a Distinguished Name component that will be used to identify the certificate to use
-        for the HTTPS WS-Man Listener if a thumbprint is not specified.
+        This is the BaseDN (path part of the full Distinguished Name) used to identify the certificate
+        to use for the HTTPS WS-Man Listener if a thumbprint is not specified.
 
     .PARAMETER CertificateThumbprint
         The Thumbprint of the certificate to use for the HTTPS WS-Man Listener.
@@ -360,8 +360,8 @@ function Set-TargetResource
         Listener if a thumbprint is not specified.
 
     .PARAMETER DN
-        This is a Distinguished Name component that will be used to identify the certificate to use
-        for the HTTPS WS-Man Listener if a thumbprint is not specified.
+        This is the BaseDN (path part of the full Distinguished Name) used to identify the certificate
+        to use for the HTTPS WS-Man Listener if a thumbprint is not specified.
 
     .PARAMETER CertificateThumbprint
         The Thumbprint of the certificate to use for the HTTPS WS-Man Listener.
@@ -589,8 +589,8 @@ function Get-DefaultPort
         Listener if a thumbprint is not specified.
 
     .PARAMETER DN
-        This is a Distinguished Name component that will be used to identify the certificate to use
-        for the HTTPS WS-Man Listener if a thumbprint is not specified.
+        This is the BaseDN (path part of the full Distinguished Name) used to identify the certificate
+        to use for the HTTPS WS-Man Listener if a thumbprint is not specified.
 
     .PARAMETER CertificateThumbprint
         The Thumbprint of the certificate to use for the HTTPS WS-Man Listener.

diff --git a/source/DSCResources/DSC_WSManListener/DSC_WSManListener.schema.mof b/source/DSCResources/DSC_WSManListener/DSC_WSManListener.schema.mof
@@ -8,7 +8,7 @@ class DSC_WSManListener : OMI_BaseResource
     [Write, Description("The Issuer of the certificate to use for the HTTPS WS-Man Listener if a thumbprint is not specified.")] String Issuer;
     [Write, Description("The format used to match the certificate subject to use for an HTTPS WS-Man Listener if a thumbprint is not specified."), ValueMap{"Both","FQDNOnly","NameOnly"}, Values{"Both","FQDNOnly","NameOnly"}] String SubjectFormat;
     [Write, Description("Should the FQDN/Name be used to also match the certificate alternate subject for an HTTPS WS-Man Listener if a thumbprint is not specified.")] Boolean MatchAlternate;
-    [Write, Description("This is a Distinguished Name component that will be used to identify the certificate to use for the HTTPS WS-Man Listener if a thumbprint is not specified.")] String DN;
+    [Write, Description("This is the BaseDN (base of the full Distinguished Name) used to identify the certificate to use for the HTTPS WS-Man Listener if a thumbprint is not specified.")] String DN;
     [Write, Description("The host name that a HTTPS WS-Man Listener will be bound to. If not specified it will default to the computer name of the node.")] String Hostname;
     [Read, Description("Returns true if the existing WS-Man Listener is enabled.")] Boolean Enabled;
     [Read, Description("The URL Prefix of the existing WS-Man Listener.")] String URLPrefix;

diff --git a/tests/Integration/DSC_WSManListener.Integration.Tests.ps1 b/tests/Integration/DSC_WSManListener.Integration.Tests.ps1
@@ -91,8 +91,8 @@ try
         Remove-Item -Force
 
     $Hostname = ([System.Net.Dns]::GetHostByName($ENV:computerName).Hostname)
-    $DN = 'O=Contoso Inc, S=Pennsylvania, C=US'
-    $Issuer = "CN=$Hostname, $DN"
+    $BaseDN = 'O=Contoso Inc, S=Pennsylvania, C=US'
+    $Issuer = "CN=$Hostname, $BaseDN"
 
     # Create the certificate
     if ([System.Environment]::OSVersion.Version.Major -ge 10)
@@ -146,7 +146,7 @@ try
                     Issuer         = $Issuer
                     SubjectFormat  = 'Both'
                     MatchAlternate = $False
-                    DN             = $DN
+                    BaseDN         = $BaseDN
                     Hostname       = $Hostname
                 }
             )

diff --git a/tests/Integration/DSC_WSManListener_Add_HTTPS.config.ps1 b/tests/Integration/DSC_WSManListener_Add_HTTPS.config.ps1
@@ -10,7 +10,7 @@ Configuration DSC_WSManListener_Config_Add_HTTPS {
             Issuer         = $Node.Issuer
             SubjectFormat  = $Node.SubjectFormat
             MatchAlternate = $Node.MatchAlternate
-            DN             = $Node.DN
+            DN             = $Node.BaseDN
         }
     }
 }
diff --git a/tests/Unit/DSC_WSManListener.Tests.ps1 b/tests/Unit/DSC_WSManListener.Tests.ps1
@@ -34,7 +34,7 @@ try
         $mockCertificateThumbprint = '74FA31ADEA7FDD5333CED10910BFA6F665A1F2FC'
         $mockHostName = $([System.Net.Dns]::GetHostByName($ENV:computerName).Hostname)
         $mockIssuer = 'CN=CONTOSO.COM Issuing CA, DC=CONTOSO, DC=COM'
-        $mockDN = 'O=Contoso Inc, S=Pennsylvania, C=US'
+        $mockBaseDN = 'O=Contoso Inc, S=Pennsylvania, C=US'
 
         $mockCertificate = [PSObject] @{
             Thumbprint = $mockCertificateThumbprint
@@ -44,9 +44,9 @@ try
             DNSNameList = @{ Unicode = $mockHostName }
         }
 
-        $mockCertificateDN = [PSObject] @{
+        $mockCertificateWithBaseDN = [PSObject] @{
             Thumbprint = $mockCertificateThumbprint
-            Subject = "CN=$mockHostName, $mockDN"
+            Subject = "CN=$mockHostName, $mockBaseDN"
             Issuer = $mockIssuer
             Extensions = @{ EnhancedKeyUsages = @{ FriendlyName = 'Server Authentication' } }
             DNSNameList = @{ Unicode = $mockHostName }
@@ -500,7 +500,7 @@ try
 
             Context 'CertificateThumbprint is passed and does exist' {
                 Mock -CommandName Get-ChildItem -MockWith {
-                    $mockCertificateDN
+                    $mockCertificateWithBaseDN
                 }
 
                 It 'Should not throw error' {
@@ -526,7 +526,7 @@ try
                         -Issuer $mockIssuer `
                         -SubjectFormat 'Both' `
                         -MatchAlternate $True `
-                        -DN $mockDN  `
+                        -DN $mockBaseDN  `
                         -Verbose } | Should -Not -Throw
                 }
 
@@ -541,15 +541,15 @@ try
 
             Context 'SubjectFormat is Both, Certificate with DN Exists, DN passed' {
                 Mock -CommandName Get-ChildItem -MockWith {
-                    $mockCertificateDN
+                    $mockCertificateWithBaseDN
                 }
 
                 It 'Should not throw error' {
                     { $script:returnedCertificate = Find-Certificate `
                         -Issuer $mockIssuer `
                         -SubjectFormat 'Both' `
                         -MatchAlternate $True `
-                        -DN $mockDN  `
+                        -DN $mockBaseDN  `
                         -Verbose } | Should -Not -Throw
                 }
 
@@ -562,7 +562,7 @@ try
                 }
             }
 
-            Context 'SubjectFormat is Both, Certificate without DN Exists, DN passed' {
+            Context 'SubjectFormat is Both, Certificate without Base DN Exists, DN passed' {
                 Mock -CommandName Get-ChildItem -MockWith {
                     $mockCertificate
                 }
@@ -572,7 +572,7 @@ try
                         -Issuer $mockIssuer `
                         -SubjectFormat 'Both' `
                         -MatchAlternate $True `
-                        -DN $mockDN  `
+                        -DN $mockBaseDN  `
                         -Verbose } | Should -Not -Throw
                 }
 
@@ -605,9 +605,9 @@ try
                 }
             }
 
-            Context 'SubjectFormat is Both, Certificate with DN Exists, DN not passed' {
+            Context 'SubjectFormat is Both, Certificate with Base DN Exists, DN not passed' {
                 Mock -CommandName Get-ChildItem -MockWith {
-                    $mockCertificateDN
+                    $mockCertificateWithBaseDN
                 }
 
                 It 'Should not throw error' {
@@ -627,7 +627,7 @@ try
                 }
             }
 
-            Context 'SubjectFormat is Both, Certificate without DN Exists, DN not passed' {
+            Context 'SubjectFormat is Both, Certificate without Base DN Exists, DN not passed' {
                 Mock -CommandName Get-ChildItem -MockWith {
                     $mockCertificate
                 }