Add "external mu" variant of ML-DSA (65 and 87) in _CryptoExtras

Package.swift

@@ -171,7 +171,7 @@ let package = Package(
                 "Key Agreement/ECDH.swift.gyb",
                 "Signatures/ECDSA.swift.gyb",
                 "Signatures/MLDSA.swift.gyb",
-                "Signatures/BoringSSL/MLDSA_boring.swift.gyb",
+                "Signatures/BoringSSL/MLDSA+externalMu_boring.swift.gyb",
                 "KEM/MLKEM.swift.gyb",
                 "KEM/BoringSSL/MLKEM_boring.swift.gyb",
             ],
@@ -188,7 +188,8 @@ let package = Package(
                 .product(name: "SwiftASN1", package: "swift-asn1"),
             ],
             exclude: privacyManifestExclude + [
-                "CMakeLists.txt"
+                "CMakeLists.txt",
+                "MLDSA/MLDSA+externalMu.swift.gyb",
             ],
             resources: privacyManifestResource,
             swiftSettings: swiftSettings
@@ -207,7 +208,8 @@ let package = Package(
                 "CCryptoBoringSSLShims",
             ],
             exclude: privacyManifestExclude + [
-                "CMakeLists.txt"
+                "CMakeLists.txt",
+                "MLDSA/BoringSSLMLDSA.swift.gyb",
             ],
             resources: privacyManifestResource
         ),

Sources/Crypto/CMakeLists.txt

@@ -91,7 +91,7 @@ add_library(Crypto
   "Signatures/BoringSSL/ECDSASignature_boring.swift"
   "Signatures/BoringSSL/ECDSA_boring.swift"
   "Signatures/BoringSSL/EdDSA_boring.swift"
-  "Signatures/BoringSSL/MLDSA_boring.swift"
+  "Signatures/BoringSSL/MLDSA+externalMu_boring.swift"
   "Signatures/BoringSSL/MLDSA_wrapper.swift"
   "Signatures/ECDSA.swift"
   "Signatures/Ed25519.swift"

Sources/Crypto/Docs.docc/index.md

@@ -39,11 +39,25 @@ Swift Crypto is built on top of [BoringSSL](https://boringssl.googlesource.com/b
 - ``P256``
 - ``SharedSecret``
 - ``HPKE``
+- ``MLDSA65``
+- ``MLDSA87``
 
 ### Key derivation functions
 
 - ``HKDF``
 
+### Key encapsulation mechanisms (KEM)
+
+- ``KEM``
+- ``MLKEM768``
+- ``MLKEM1024``
+- ``XWingMLKEM768X25519``
+
+### KEM keys
+
+- ``KEMPrivateKey``
+- ``KEMPublicKey``
+
 ### Errors
 
 - ``CryptoKitError``

Sources/Crypto/Signatures/BoringSSL/MLDSA+externalMu_boring.swift

@@ -0,0 +1,145 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftCrypto open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+// MARK: - Generated file, do NOT edit
+// any edits of this file WILL be overwritten and thus discarded
+// see section `gyb` in `README` for details.
+
+#if (!CRYPTO_IN_SWIFTPM) || CRYPTO_IN_SWIFTPM_FORCE_BUILD_API
+#if canImport(FoundationEssentials)
+import FoundationEssentials
+#else
+import Foundation
+#endif
+
+@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
+extension MLDSA65.PublicKey {
+    /// Generate a prehashed message representative (a.k.a. "external mu") for the given message.
+    ///
+    /// - Parameter data: The message to prehash.
+    ///
+    /// - Returns: The prehashed message representative (a.k.a. "external mu").
+    package func prehash_boring<D: DataProtocol>(for data: D) throws -> Data {
+        try self.boringSSLKey.prehash_boring(for: data)
+    }
+
+    /// Generate a prehashed message representative (a.k.a. "external mu") for the given message.
+    ///
+    /// - Parameters:
+    ///   - data: The message to prehash.
+    ///   - context: The context of the message.
+    ///
+    /// - Returns: The prehashed message representative (a.k.a. "external mu").
+    package func prehash_boring<D: DataProtocol, C: DataProtocol>(for data: D, context: C) throws -> Data {
+        try self.boringSSLKey.prehash_boring(for: data, context: context)
+    }
+
+    private var boringSSLKey: OpenSSLMLDSAPublicKeyImpl<MLDSA65> {
+        get throws {
+            #if (!CRYPTO_IN_SWIFTPM_FORCE_BUILD_API) || CRYPTOKIT_NO_ACCESS_TO_FOUNDATION
+            try OpenSSLMLDSAPublicKeyImpl<MLDSA65>(rawRepresentation: self.rawRepresentation)
+            #else
+            self.impl
+            #endif
+        }
+    }
+}
+
+@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
+extension MLDSA65.PrivateKey {
+    /// Generate a signature for the prehashed message representative (a.k.a. "external mu").
+    ///
+    /// > Note: The message representative should be obtained via calls to ``MLDSA87/PublicKey/prehash(for:context:)``.
+    ///
+    /// - Parameter mu: The prehashed message representative (a.k.a. "external mu").
+    ///
+    /// - Returns: The signature of the prehashed message representative.
+    package func signature_boring(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data {
+        try self.boringSSLKey.signature_boring(forPrehashedMessageRepresentative: mu)
+    }
+
+    private var boringSSLKey: OpenSSLMLDSAPrivateKeyImpl<MLDSA65> {
+        get throws {
+            #if (!CRYPTO_IN_SWIFTPM_FORCE_BUILD_API) || CRYPTOKIT_NO_ACCESS_TO_FOUNDATION
+            try OpenSSLMLDSAPrivateKeyImpl<MLDSA65>(
+                seedRepresentation: self.seedRepresentation,
+                publicKey: nil
+            )
+            #else
+            self.impl
+            #endif
+        }
+    }
+}
+
+@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
+extension MLDSA87.PublicKey {
+    /// Generate a prehashed message representative (a.k.a. "external mu") for the given message.
+    ///
+    /// - Parameter data: The message to prehash.
+    ///
+    /// - Returns: The prehashed message representative (a.k.a. "external mu").
+    package func prehash_boring<D: DataProtocol>(for data: D) throws -> Data {
+        try self.boringSSLKey.prehash_boring(for: data)
+    }
+
+    /// Generate a prehashed message representative (a.k.a. "external mu") for the given message.
+    ///
+    /// - Parameters:
+    ///   - data: The message to prehash.
+    ///   - context: The context of the message.
+    ///
+    /// - Returns: The prehashed message representative (a.k.a. "external mu").
+    package func prehash_boring<D: DataProtocol, C: DataProtocol>(for data: D, context: C) throws -> Data {
+        try self.boringSSLKey.prehash_boring(for: data, context: context)
+    }
+
+    private var boringSSLKey: OpenSSLMLDSAPublicKeyImpl<MLDSA87> {
+        get throws {
+            #if (!CRYPTO_IN_SWIFTPM_FORCE_BUILD_API) || CRYPTOKIT_NO_ACCESS_TO_FOUNDATION
+            try OpenSSLMLDSAPublicKeyImpl<MLDSA87>(rawRepresentation: self.rawRepresentation)
+            #else
+            self.impl
+            #endif
+        }
+    }
+}
+
+@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
+extension MLDSA87.PrivateKey {
+    /// Generate a signature for the prehashed message representative (a.k.a. "external mu").
+    ///
+    /// > Note: The message representative should be obtained via calls to ``MLDSA87/PublicKey/prehash(for:context:)``.
+    ///
+    /// - Parameter mu: The prehashed message representative (a.k.a. "external mu").
+    ///
+    /// - Returns: The signature of the prehashed message representative.
+    package func signature_boring(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data {
+        try self.boringSSLKey.signature_boring(forPrehashedMessageRepresentative: mu)
+    }
+
+    private var boringSSLKey: OpenSSLMLDSAPrivateKeyImpl<MLDSA87> {
+        get throws {
+            #if (!CRYPTO_IN_SWIFTPM_FORCE_BUILD_API) || CRYPTOKIT_NO_ACCESS_TO_FOUNDATION
+            try OpenSSLMLDSAPrivateKeyImpl<MLDSA87>(
+                seedRepresentation: self.seedRepresentation,
+                publicKey: nil
+            )
+            #else
+            self.impl
+            #endif
+        }
+    }
+}
+#endif  // Linux or !SwiftPM

Sources/Crypto/Signatures/BoringSSL/MLDSA+externalMu_boring.swift.gyb

@@ -0,0 +1,90 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftCrypto open source project
+//
+// Copyright (c) 2025 Apple Inc. and the SwiftCrypto project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftCrypto project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//
+
+// MARK: - Generated file, do NOT edit
+// any edits of this file WILL be overwritten and thus discarded
+// see section `gyb` in `README` for details.
+
+#if (!CRYPTO_IN_SWIFTPM) || CRYPTO_IN_SWIFTPM_FORCE_BUILD_API
+#if canImport(FoundationEssentials)
+import FoundationEssentials
+#else
+import Foundation
+#endif
+%{
+    parameter_sets = ["65", "87"]
+}%
+% for parameter_set in parameter_sets:
+
+@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
+extension MLDSA${parameter_set}.PublicKey {
+    /// Generate a prehashed message representative (a.k.a. "external mu") for the given message.
+    ///
+    /// - Parameter data: The message to prehash.
+    ///
+    /// - Returns: The prehashed message representative (a.k.a. "external mu").
+    package func prehash_boring<D: DataProtocol>(for data: D) throws -> Data {
+        try self.boringSSLKey.prehash_boring(for: data)
+    }
+
+    /// Generate a prehashed message representative (a.k.a. "external mu") for the given message.
+    ///
+    /// - Parameters:
+    ///   - data: The message to prehash.
+    ///   - context: The context of the message.
+    ///
+    /// - Returns: The prehashed message representative (a.k.a. "external mu").
+    package func prehash_boring<D: DataProtocol, C: DataProtocol>(for data: D, context: C) throws -> Data {
+        try self.boringSSLKey.prehash_boring(for: data, context: context)
+    }
+
+    private var boringSSLKey: OpenSSLMLDSAPublicKeyImpl<MLDSA${parameter_set}> {
+        get throws {
+            #if (!CRYPTO_IN_SWIFTPM_FORCE_BUILD_API) || CRYPTOKIT_NO_ACCESS_TO_FOUNDATION
+            try OpenSSLMLDSAPublicKeyImpl<MLDSA${parameter_set}>(rawRepresentation: self.rawRepresentation)
+            #else
+            self.impl
+            #endif
+        }
+    }
+}
+
+@available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
+extension MLDSA${parameter_set}.PrivateKey {
+    /// Generate a signature for the prehashed message representative (a.k.a. "external mu").
+    ///
+    /// > Note: The message representative should be obtained via calls to ``MLDSA87/PublicKey/prehash(for:context:)``.
+    ///
+    /// - Parameter mu: The prehashed message representative (a.k.a. "external mu").
+    ///
+    /// - Returns: The signature of the prehashed message representative.
+    package func signature_boring(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data {
+        try self.boringSSLKey.signature_boring(forPrehashedMessageRepresentative: mu)
+    }
+
+    private var boringSSLKey: OpenSSLMLDSAPrivateKeyImpl<MLDSA${parameter_set}> {
+        get throws {
+            #if (!CRYPTO_IN_SWIFTPM_FORCE_BUILD_API) || CRYPTOKIT_NO_ACCESS_TO_FOUNDATION
+            try OpenSSLMLDSAPrivateKeyImpl<MLDSA${parameter_set}>(
+                seedRepresentation: self.seedRepresentation,
+                publicKey: nil
+            )
+            #else
+            self.impl
+            #endif
+        }
+    }
+}
+% end
+#endif  // Linux or !SwiftPM

Sources/Crypto/Signatures/BoringSSL/MLDSA_wrapper.swift

@@ -16,6 +16,7 @@
 @_exported import CryptoKit
 #else
 @_implementationOnly import CCryptoBoringSSL
+import CryptoBoringWrapper
 #if canImport(FoundationEssentials)
 import FoundationEssentials
 #else
@@ -34,6 +35,8 @@ protocol BoringSSLBackedMLDSAPrivateKey: Sendable {
 
     func signature<D: DataProtocol, C: DataProtocol>(for data: D, context: C) throws -> Data
 
+    func signature(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data
+
     var publicKey: AssociatedPublicKey { get }
 
     var seedRepresentation: Data { get }
@@ -48,6 +51,10 @@ protocol BoringSSLBackedMLDSAPublicKey: Sendable {
     func isValidSignature<S: DataProtocol, D: DataProtocol, C: DataProtocol>(_: S, for data: D, context: C) -> Bool
 
     var rawRepresentation: Data { get }
+
+    func prehash<D: DataProtocol>(for data: D) throws -> Data
+
+    func prehash<D: DataProtocol, C: DataProtocol>(for data: D, context: C) throws -> Data
 }
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
@@ -59,27 +66,27 @@ protocol BoringSSLBackedMLDSAParameters {
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
 extension MLDSA65: BoringSSLBackedMLDSAParameters {
-    typealias BackingPrivateKey = MLDSA65.InternalPrivateKey
-    typealias BackingPublicKey = MLDSA65.InternalPublicKey
+    typealias BackingPrivateKey = BoringSSLMLDSA65.InternalPrivateKey
+    typealias BackingPublicKey = BoringSSLMLDSA65.InternalPublicKey
 }
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
 extension MLDSA87: BoringSSLBackedMLDSAParameters {
-    typealias BackingPrivateKey = MLDSA87.InternalPrivateKey
-    typealias BackingPublicKey = MLDSA87.InternalPublicKey
+    typealias BackingPrivateKey = BoringSSLMLDSA87.InternalPrivateKey
+    typealias BackingPublicKey = BoringSSLMLDSA87.InternalPublicKey
 }
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
-extension MLDSA65.InternalPrivateKey: BoringSSLBackedMLDSAPrivateKey {}
+extension BoringSSLMLDSA65.InternalPrivateKey: BoringSSLBackedMLDSAPrivateKey {}
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
-extension MLDSA65.InternalPublicKey: BoringSSLBackedMLDSAPublicKey {}
+extension BoringSSLMLDSA65.InternalPublicKey: BoringSSLBackedMLDSAPublicKey {}
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
-extension MLDSA87.InternalPrivateKey: BoringSSLBackedMLDSAPrivateKey {}
+extension BoringSSLMLDSA87.InternalPrivateKey: BoringSSLBackedMLDSAPrivateKey {}
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
-extension MLDSA87.InternalPublicKey: BoringSSLBackedMLDSAPublicKey {}
+extension BoringSSLMLDSA87.InternalPublicKey: BoringSSLBackedMLDSAPublicKey {}
 
 @available(macOS 10.15, iOS 13, watchOS 6, tvOS 13, macCatalyst 13, visionOS 1.0, *)
 struct OpenSSLMLDSAPrivateKeyImpl<Parameters: BoringSSLBackedMLDSAParameters> {
@@ -117,6 +124,10 @@ struct OpenSSLMLDSAPrivateKeyImpl<Parameters: BoringSSLBackedMLDSAParameters> {
         try self.backing.signature(for: data, context: context)
     }
 
+    func signature_boring(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data {
+        try self.backing.signature(forPrehashedMessageRepresentative: mu)
+    }
+
     var publicKey: OpenSSLMLDSAPublicKeyImpl<Parameters> {
         .init(backing: self.backing.publicKey)
     }
@@ -135,7 +146,7 @@ struct OpenSSLMLDSAPrivateKeyImpl<Parameters: BoringSSLBackedMLDSAParameters> {
     }
 
     static var seedSize: Int {
-        MLDSA.seedByteCount
+        BoringSSLMLDSA.seedByteCount
     }
 }
 
@@ -169,6 +180,14 @@ struct OpenSSLMLDSAPublicKeyImpl<Parameters: BoringSSLBackedMLDSAParameters> {
     var rawRepresentation: Data {
         self.backing.rawRepresentation
     }
+
+    func prehash_boring<D: DataProtocol>(for data: D) throws -> Data {
+        try self.backing.prehash(for: data)
+    }
+
+    func prehash_boring<D: DataProtocol, C: DataProtocol>(for data: D, context: C) throws -> Data {
+        try self.backing.prehash(for: data, context: context)
+    }
 }
 
 #endif  // CRYPTO_IN_SWIFTPM && !CRYPTO_IN_SWIFTPM_FORCE_BUILD_API