Feature: Enhance RDN parsing to support IA5String (#236)

erikgadireddi · web-flow · commit bdcbccd1bd31 · 2025-04-10T14:00:00.000Z
Add capability of converting RDN value of ASN1IA5String to String, if I
am correct all RFC expect that RDN value can be ASN1IA5String..
- additionally fix tests after this change
- added DN components emailAddress(E) and domainComponent(DC)
diff --git a/Sources/X509/CMakeLists.txt b/Sources/X509/CMakeLists.txt
@@ -40,6 +40,8 @@ add_library(X509
   "DistinguishedNameBuilder/CommonName.swift"
   "DistinguishedNameBuilder/CountryName.swift"
   "DistinguishedNameBuilder/DNBuilder.swift"
+  "DistinguishedNameBuilder/DomainComponent.swift"
+  "DistinguishedNameBuilder/EmailAddress.swift"
   "DistinguishedNameBuilder/LocalityName.swift"
   "DistinguishedNameBuilder/OrganizationName.swift"
   "DistinguishedNameBuilder/OrganizationalUnitName.swift"
diff --git a/Sources/X509/DistinguishedNameBuilder/DomainComponent.swift b/Sources/X509/DistinguishedNameBuilder/DomainComponent.swift
@@ -0,0 +1,38 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftCertificates open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftCertificates project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftCertificates project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftASN1
+
+/// Set the Domain Component (DC) of a ``DistinguishedName``.
+///
+/// This type is used in ``DistinguishedNameBuilder`` contexts.
+public struct DomainComponent: RelativeDistinguishedNameConvertible {
+    /// The value of the organizational unit name field.
+    public var name: String
+
+    /// Construct a new organizational unit name
+    ///
+    /// - Parameter name: The value of the organizational unit name
+    @inlinable
+    public init(_ name: String) {
+        self.name = name
+    }
+
+    @inlinable
+    public func makeRDN() throws -> RelativeDistinguishedName {
+        return RelativeDistinguishedName(
+            try .init(type: .RDNAttributeType.domainComponent, ia5String: name)
+        )
+    }
+}
diff --git a/Sources/X509/DistinguishedNameBuilder/EmailAddress.swift b/Sources/X509/DistinguishedNameBuilder/EmailAddress.swift
@@ -0,0 +1,38 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftCertificates open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftCertificates project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftCertificates project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+import SwiftASN1
+
+/// Set the Domain Component (E) of a ``DistinguishedName``.
+///
+/// This type is used in ``DistinguishedNameBuilder`` contexts.
+public struct EmailAddress: RelativeDistinguishedNameConvertible {
+    /// The value of the email name field.
+    public var name: String
+
+    /// Construct a new organizational unit name
+    ///
+    /// - Parameter name: The value of the organizational unit name
+    @inlinable
+    public init(_ name: String) {
+        self.name = name
+    }
+
+    @inlinable
+    public func makeRDN() throws -> RelativeDistinguishedName {
+        return RelativeDistinguishedName(
+            try .init(type: .RDNAttributeType.emailAddress, ia5String: name)
+        )
+    }
+}
diff --git a/Sources/X509/Docs.docc/index.md b/Sources/X509/Docs.docc/index.md
@@ -75,6 +75,8 @@ certificate authorities, authenticating peers, and more.
 - ``OrganizationName``
 - ``StateOrProvinceName``
 - ``StreetAddress``
+- ``DomainComponent``
+- ``EmailAddress``
 
 ### Verifying Certificates
 
diff --git a/Sources/X509/RDNAttribute.swift b/Sources/X509/RDNAttribute.swift
@@ -33,7 +33,9 @@ extension RelativeDistinguishedName {
                 case printable(String)
                 /// ``ASN1UTF8String``
                 case utf8(String)
-                /// `.any` can never contain bytes which are equal to the DER representation of `.printable` or `.utf8`.
+                /// ``ASN1IA5String``
+                case ia5(String)
+                /// `.any` can never contain bytes which are equal to the DER representation of `.printable`, `.utf8` or `.ia5`.
                 /// This invariant must not be violated or otherwise the synthesised `Hashable` would be wrong.
                 case any(ASN1Any)
             }
@@ -76,6 +78,9 @@ extension ASN1Any {
         case .utf8(let utf8String):
             // force try is safe because we verify in the initialiser that it is valid
             self = try! .init(erasing: ASN1UTF8String(utf8String))
+        case .ia5(let ia5String):
+            // force try is safe because we verify in the initialiser that it is valid
+            self = try! .init(erasing: ASN1IA5String(ia5String))
         case .any(let any):
             self = any
         }
@@ -106,6 +111,14 @@ extension RelativeDistinguishedName.Attribute.Value {
         self.storage = .printable(printableString)
     }
 
+    /// A helper constructor to construct a ``RelativeDistinguishedName/Attribute/Value`` with an `ASN1IA5String`.
+    @inlinable
+    public init(ia5String: String) throws {
+        // verify that it is indeed a ASN1IA5String
+        _ = try ASN1IA5String(ia5String)
+        self.storage = .ia5(ia5String)
+    }
+
     @inlinable
     public init(asn1Any: ASN1Any) {
         do {
@@ -125,6 +138,8 @@ extension RelativeDistinguishedName.Attribute.Value.Storage: DERParseable, DERSe
                 self = .utf8(String(try ASN1UTF8String(derEncoded: node)))
             case ASN1PrintableString.defaultIdentifier:
                 self = .printable(String(try ASN1PrintableString(derEncoded: node)))
+            case ASN1IA5String.defaultIdentifier:
+                self = .ia5(String(try ASN1IA5String(derEncoded: node)))
             default:
                 self = .any(ASN1Any(derEncoded: node))
             }
@@ -143,6 +158,10 @@ extension RelativeDistinguishedName.Attribute.Value.Storage: DERParseable, DERSe
         case .utf8(let utf8String):
             let string = ASN1UTF8String(utf8String)
             try string.serialize(into: &coder)
+        case .ia5(let ia5String):
+            // force try is safe because we verify in the initialiser that it is valid
+            let string = try! ASN1IA5String(ia5String)
+            try string.serialize(into: &coder)
         case .any(let any):
             try any.serialize(into: &coder)
         }
@@ -220,6 +239,10 @@ extension RelativeDistinguishedName.Attribute: CustomStringConvertible {
             attributeKey = "OU"
         case .RDNAttributeType.streetAddress:
             attributeKey = "STREET"
+        case .RDNAttributeType.domainComponent:
+            attributeKey = "DC"
+        case .RDNAttributeType.emailAddress:
+            attributeKey = "E"
         case let type:
             attributeKey = String(describing: type)
         }
@@ -275,6 +298,12 @@ extension RelativeDistinguishedName.Attribute {
         self.value = try .init(printableString: printableString)
     }
 
+    @inlinable
+    public init(type: ASN1ObjectIdentifier, ia5String: String) throws {
+        self.type = type
+        self.value = try .init(ia5String: ia5String)
+    }
+
     /// Create a new attribute from a given type and value.
     ///
     /// - Parameter type: The type of the attribute.
@@ -318,6 +347,13 @@ extension ASN1ObjectIdentifier {
         /// information from a postal address (i.e., the street name, place,
         /// avenue, and the house number).
         public static let streetAddress: ASN1ObjectIdentifier = [2, 5, 4, 9]
+
+        /// The `domainComponent` attribute type contains parts (labels) of a DNS domain name
+        public static let domainComponent: ASN1ObjectIdentifier = [0, 9, 2342, 19_200_300, 100, 1, 25]
+
+        /// The `emailAddress` attribute type contains email address defined in PCKS#9 (RFC2985).
+        /// Be aware that, modern best practices (e.g., RFC 5280) discourage embedding email addresses in the `Subject DN` instead it should be in  `Subject Alternative Name (SAN)
+        public static let emailAddress: ASN1ObjectIdentifier = [1, 2, 840, 113549, 1, 9, 1]
     }
 }
 
@@ -331,6 +367,8 @@ extension String {
             self = printable
         case .utf8(let utf8):
             self = utf8
+        case .ia5(let ia5):
+            self = ia5
         case .any:
             return nil
         }
diff --git a/Tests/X509Tests/DistinguishedNameTests.swift b/Tests/X509Tests/DistinguishedNameTests.swift
@@ -211,6 +211,9 @@ final class DistinguishedNameTests: XCTestCase {
             OrganizationName("DigiCert Inc")
             OrganizationalUnitName("www.digicert.com")
             CommonName("DigiCert Global Root G3")
+            EmailAddress("jon.doe@apple.com")
+            DomainComponent("apple")
+            DomainComponent("com")
         }
         XCTAssertEqual(
             name,
@@ -228,6 +231,12 @@ final class DistinguishedNameTests: XCTestCase {
                     type: .RDNAttributeType.commonName,
                     utf8String: "DigiCert Global Root G3"
                 ),
+                RelativeDistinguishedName.Attribute(
+                    type: .RDNAttributeType.emailAddress,
+                    ia5String: "jon.doe@apple.com"
+                ),
+                RelativeDistinguishedName.Attribute(type: .RDNAttributeType.domainComponent, ia5String: "apple"),
+                RelativeDistinguishedName.Attribute(type: .RDNAttributeType.domainComponent, ia5String: "com"),
             ])
         )
     }
@@ -280,6 +289,9 @@ final class DistinguishedNameTests: XCTestCase {
 
     func testDistinguishedNameRepresentation() throws {
         let name = try DistinguishedName([
+            RelativeDistinguishedName.Attribute(type: .RDNAttributeType.domainComponent, ia5String: "com"),
+            RelativeDistinguishedName.Attribute(type: .RDNAttributeType.domainComponent, ia5String: "apple"),
+            RelativeDistinguishedName.Attribute(type: .RDNAttributeType.emailAddress, ia5String: "jon.doe@apple.com"),
             RelativeDistinguishedName.Attribute(type: .RDNAttributeType.countryName, utf8String: "US"),
             RelativeDistinguishedName.Attribute(type: .RDNAttributeType.organizationName, utf8String: "DigiCert Inc"),
             RelativeDistinguishedName.Attribute(
@@ -290,14 +302,30 @@ final class DistinguishedNameTests: XCTestCase {
                 type: .RDNAttributeType.commonName,
                 utf8String: "DigiCert Global Root G3"
             ),
+
         ])
 
         let s = String(describing: name)
-        XCTAssertEqual(s, "CN=DigiCert Global Root G3,OU=www.digicert.com,O=DigiCert Inc,C=US")
+        XCTAssertEqual(
+            s,
+            "CN=DigiCert Global Root G3,OU=www.digicert.com,O=DigiCert Inc,C=US,E=jon.doe@apple.com,DC=apple,DC=com"
+        )
     }
 
     func testDistinguishedNameRepresentationWithNestedAttributes() throws {
         let name = try DistinguishedName([
+            RelativeDistinguishedName([
+                RelativeDistinguishedName.Attribute(type: .RDNAttributeType.domainComponent, ia5String: "com")
+            ]),
+            RelativeDistinguishedName([
+                RelativeDistinguishedName.Attribute(type: .RDNAttributeType.domainComponent, ia5String: "apple")
+            ]),
+            RelativeDistinguishedName([
+                RelativeDistinguishedName.Attribute(
+                    type: .RDNAttributeType.emailAddress,
+                    ia5String: "jon.doe@apple.com"
+                )
+            ]),
             RelativeDistinguishedName([
                 RelativeDistinguishedName.Attribute(type: .RDNAttributeType.countryName, utf8String: "US")
             ]),
@@ -329,7 +357,10 @@ final class DistinguishedNameTests: XCTestCase {
         ])
 
         let s = String(describing: name)
-        XCTAssertEqual(s, "CN=DigiCert Global Root G3,OU=www.digicert.com,O=DigiCert Inc,ST=CA+ST=California,C=US")
+        XCTAssertEqual(
+            s,
+            "CN=DigiCert Global Root G3,OU=www.digicert.com,O=DigiCert Inc,ST=CA+ST=California,C=US,E=jon.doe@apple.com,DC=apple,DC=com"
+        )
     }
 
     func testDistinguishedNameRepresentationWithCommasAndNewlines() throws {
@@ -420,7 +451,17 @@ final class DistinguishedNameTests: XCTestCase {
         let examplesAndResults: [(RelativeDistinguishedName.Attribute, String?)] = try [
             (.init(type: .RDNAttributeType.commonName, printableString: "foo"), "foo"),
             (.init(type: .RDNAttributeType.commonName, utf8String: "bar"), "bar"),
-            (.init(type: .RDNAttributeType.commonName, value: ASN1Any(erasing: ASN1IA5String("foo"))), nil),
+            (.init(type: .RDNAttributeType.commonName, ia5String: "foo"), "foo"),
+            /// ASN1IA5String with wrong tag
+            (
+                .init(type: .RDNAttributeType.commonName, value: ASN1Any(derEncoded: [0x19, 0x03, 0x41, 0x42, 0x43])),
+                nil
+            ),
+            /// ASN1IA5String byte that falls outside the range of 7-bit ASCII
+            (
+                .init(type: .RDNAttributeType.commonName, value: ASN1Any(derEncoded: [0x16, 0x03, 0x41, 0x42, 0x80])),
+                nil
+            ),
         ]
 
         for (example, result) in examplesAndResults {
@@ -436,7 +477,7 @@ final class DistinguishedNameTests: XCTestCase {
             (.init(type: weirdOID, utf8String: "bar"), "bar"),
             (.init(type: weirdOID, value: ASN1Any(erasing: ASN1UTF8String("foo"))), "foo"),
             (.init(type: weirdOID, value: ASN1Any(erasing: ASN1PrintableString("baz"))), "baz"),
-            (.init(type: weirdOID, value: ASN1Any(erasing: ASN1IA5String("foo"))), nil),
+            (.init(type: weirdOID, value: ASN1Any(erasing: ASN1IA5String("foo"))), "foo"),
             (.init(type: weirdOID, value: ASN1Any(erasing: 5)), nil),
             (.init(type: weirdOID, value: ASN1Any(erasing: ASN1OctetString(contentBytes: [1, 2, 3, 4]))), nil),
         ]
