Add unit tests and doc strings to TryParseDistinguishedName method

Author: StefanGreve

AdvancedSystems.Security.Tests/Extensions/CertificateExtensionsTests.cs

@@ -0,0 +1,67 @@
+using AdvancedSystems.Security.Cryptography;
+using AdvancedSystems.Security.Extensions;
+
+using Xunit;
+
+namespace AdvancedSystems.Security.Tests.Extensions;
+
+/// <summary>
+///     Tests the public methods in <seealso cref="CertificateExtensions"/>.
+/// </summary>
+public sealed class CertificateExtensionsTests
+{
+    #region Tests
+
+    /// <summary>
+    ///     Tests that <seealso cref="CertificateExtensions.TryParseDistinguishedName(string, out DistinguishedName?)"/>
+    ///     extracts the RDNs from the DN correctly from the string.
+    /// </summary>
+    [Fact]
+    public void TestTryParseDistinguishedName()
+    {
+        // Arrange
+        string commonName = "Advanced Systems Root";
+        string organizationalUnit = "R&D Department";
+        string organization = "Advanced Systems Inc.";
+        string locality = "Berlin";
+        string state = "Berlin";
+        string country = "DE";
+        string distinguiedName = $"CN={commonName}, OU={organizationalUnit}, O={organization}, L={locality}, S={state}, C={country}";
+
+        // Act
+        bool isDn = CertificateExtensions.TryParseDistinguishedName(distinguiedName, out DistinguishedName? dn);
+
+        // Assert
+        Assert.Multiple(() =>
+        {
+            Assert.True(isDn);
+            Assert.NotNull(dn);
+            Assert.Equal(dn.CommonName, commonName);
+            Assert.Equal(dn.OrganizationalUnit, organizationalUnit);
+            Assert.Equal(dn.Organization, organization);
+            Assert.Equal(dn.Locality, locality);
+            Assert.Equal(dn.State, state);
+            Assert.Equal(dn.Country, country);
+        });
+    }
+
+    /// <summary>
+    ///     Tests that <seealso cref="CertificateExtensions.TryParseDistinguishedName(string, out DistinguishedName?)"/>
+    ///     when the DN is malformed.
+    /// </summary>
+    [Fact]
+    public void TestTryParseDistinguishedName_ReturnsNull()
+    {
+        // Arrange
+        string distinguishedName = string.Empty;
+
+        // Act
+        bool isDn = CertificateExtensions.TryParseDistinguishedName(distinguishedName, out DistinguishedName? dn);
+
+        // Assert
+        Assert.False(isDn);
+        Assert.Null(dn);
+    }
+
+    #endregion
+}

AdvancedSystems.Security/Extensions/CertificateExtensions.cs

@@ -7,6 +7,8 @@
 using AdvancedSystems.Security.Abstractions.Exceptions;
 using AdvancedSystems.Security.Cryptography;
 
+using static System.Net.WebRequestMethods;
+
 namespace AdvancedSystems.Security.Extensions;
 
 /// <summary>
@@ -46,7 +48,97 @@ public static X509Certificate2 GetCertificate<T>(this T store, string thumbprint
             ?? throw new CertificateNotFoundException("No valid certificate matching the search criteria could be found in the store.");
     }
 
-    public static DistinguishedName ParseDistinguishedName(string distinguishedName)
+    /// <summary>
+    ///     Attempts to parse the specified distinguished name (DN) string into a <see cref="DistinguishedName"/> object.
+    /// </summary>
+    /// <param name="distinguishedName">
+    ///     The DN string to parse, typically in the X.500 or LDAP DN format.
+    /// </param>
+    /// <param name="result">
+    ///     When this method returns, contains the parsed <see cref="DistinguishedName"/> object if the parsing was successful; 
+    ///     otherwise, <see langword="null"/>.
+    /// </param>
+    /// <returns>
+    ///     <see langword="true"/> if the parsing was successful; otherwise, <see langword="false"/>.
+    /// </returns>
+    /// <remarks>
+    ///     The X.500 Distinguished Name (DN) and the LDAP Distinguished Name (DN) differ in syntax and conventions.
+    ///     <list type="table">
+    ///         <listheader>
+    ///             <term>
+    ///                 X.500 Format
+    ///             </term>
+    ///             <description>
+    ///                 Comes from the X.500 standard for directory services
+    ///             </description>
+    ///         </listheader>
+    ///         <item>
+    ///             <term>
+    ///                 Separator
+    ///             </term>
+    ///             <description>
+    ///                 Components are separated by commas (<c>,</c>).
+    ///             </description>
+    ///         </item>
+    ///         <item>
+    ///             <term>
+    ///                 Order
+    ///             </term>
+    ///             <description>
+    ///                 Attributes are typically listed in the most significant to least significant order
+    ///                 (<i>root</i> to <i>leaf</i>).
+    ///             </description>
+    ///         </item>
+    ///         <item>
+    ///             <term>
+    ///                 Attributes
+    ///             </term>
+    ///             <description>
+    ///                 Attributes are case-insensitive but are conventionally written in uppercase. Note that
+    ///                 attribute names are more verbose in some X.500 implementations.
+    ///             </description>
+    ///         </item>
+    ///     </list>
+    ///     <list type="table">
+    ///         <listheader>
+    ///             <term>
+    ///                 LDAP
+    ///             </term>
+    ///             <description>
+    ///                 A streamlined version of the X.500 DN, tailored for LDAP (Lightweight Directory Access Protocol).
+    ///             </description>
+    ///         </listheader>
+    ///         <item>
+    ///             <term>
+    ///                 Separator
+    ///             </term>
+    ///             <description>
+    ///                 Components are separated by commas (<c>,</c>), like X.500, but semicolons (<c>;</c>) are also sometimes
+    ///                 allowed (albeit less common).
+    ///             </description>
+    ///         </item>
+    ///         <item>
+    ///             <term>
+    ///                 Order
+    ///             </term>
+    ///             <description>
+    ///                  Attributes are typically listed in the least significant to most significant order (<i>leaf</i> to <i>root</i>),
+    ///                  though many implementations allow flexibility.
+    ///             </description>
+    ///         </item>
+    ///         <item>
+    ///             <term>
+    ///                 Attributes
+    ///             </term>
+    ///             <description>
+    ///                 LDAP uses abbreviated attribute names (e.g., CN for common name, O for organization, OU for organizational unit).
+    ///                 It is also more permissive with regards to case sensitivity and attribute formatting.
+    ///             </description>
+    ///         </item>
+    ///     </list>
+    /// </remarks>
+    /// <seealso href="https://datatracker.ietf.org/doc/html/rfc4514"/>
+    public static bool TryParseDistinguishedName(string distinguishedName, out DistinguishedName? result)
     {
         var rdns = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
         var dn = new X500DistinguishedName(distinguishedName);
@@ -61,21 +153,30 @@ public static DistinguishedName ParseDistinguishedName(string distinguishedName)
             rdns.Add(attribute, value);
         }
 
-        rdns.TryGetValue(RDN.C, out string? country);
-        rdns.TryGetValue(RDN.CN, out string? commonName);
-        rdns.TryGetValue(RDN.L, out string? locality);
-        rdns.TryGetValue(RDN.O, out string? organization);
-        rdns.TryGetValue(RDN.OU, out string? organizationalUnit);
-        rdns.TryGetValue(RDN.S, out string? state);
+        bool hasCountry = rdns.TryGetValue(RDN.C, out string? country);
+        bool hasCommonName = rdns.TryGetValue(RDN.CN, out string? commonName);
+        bool hasLocality = rdns.TryGetValue(RDN.L, out string? locality);
+        bool hasOrganization = rdns.TryGetValue(RDN.O, out string? organization);
+        bool hasOrganizationalUnit = rdns.TryGetValue(RDN.OU, out string? organizationalUnit);
+        bool hasState = rdns.TryGetValue(RDN.S, out string? state);
 
-        return new DistinguishedName
+        bool hasRelativeDistinguishedNames = hasCountry
+            || hasCommonName
+            || hasLocality
+            || hasOrganization
+            || hasOrganizationalUnit
+            || hasState;
+
+        result = hasRelativeDistinguishedNames ? new DistinguishedName
         {
             CommonName = commonName,
             OrganizationalUnit = organizationalUnit,
             Organization = organization,
             Locality = locality,
             State = state,
             Country = country,
-        };
+        } : null;
+
+        return hasRelativeDistinguishedNames;
     }
 }