From 4c618280e268a9486b37c46a48e06395a66b7f38 Mon Sep 17 00:00:00 2001 From: Lucas Yamanishi Date: Mon, 20 Sep 2021 11:53:27 -0400 Subject: [PATCH] Fix DN (BaseDN) parameter docstrings In X.500 parlance, a _Distinguished Name_ (_DN_) is a fully-qualified object path[1][1],[2][2] 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_.[2][2],[3][3] Therefore, this commit updates the documentation for the `DN` parameter with the appropriate names. Fixes #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 --- .../DSC_WSManListener/DSC_WSManListener.psm1 | 12 +++++----- .../DSC_WSManListener.schema.mof | 2 +- .../DSC_WSManListener.Integration.Tests.ps1 | 6 ++--- .../DSC_WSManListener_Add_HTTPS.config.ps1 | 2 +- tests/Unit/DSC_WSManListener.Tests.ps1 | 24 +++++++++---------- 5 files changed, 23 insertions(+), 23 deletions(-) diff --git a/source/DSCResources/DSC_WSManListener/DSC_WSManListener.psm1 b/source/DSCResources/DSC_WSManListener/DSC_WSManListener.psm1 index 75631c8..60126ab 100644 --- 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 index 52cbeea..a644443 100644 --- 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 index 033a1b8..1f7076b 100644 --- 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 index d7d0eb6..fc739d1 100644 --- 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 index c267098..8766edb 100644 --- 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,7 +541,7 @@ try Context 'SubjectFormat is Both, Certificate with DN Exists, DN passed' { Mock -CommandName Get-ChildItem -MockWith { - $mockCertificateDN + $mockCertificateWithBaseDN } It 'Should not throw error' { @@ -549,7 +549,7 @@ try -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 }