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

Package.swift

@@ -186,7 +186,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

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_boring.swift

@@ -26,13 +26,6 @@ import Foundation
 // any edits of this file WILL be overwritten and thus discarded
 // see section `gyb` in `README` for details.
 
-@_implementationOnly import CCryptoBoringSSL
-#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 {
     /// A ML-DSA-65 private key.
@@ -84,6 +77,17 @@ extension MLDSA65 {
             try self.backing.signature(for: data, context: context)
         }
 
+        /// Generate a signature for the prehashed message representative (a.k.a. "external mu").
+        ///
+        /// > Note: The message representative should be obtained via calls to ``MLDSA65/PublicKey/prehash(for:context:)``.
+        ///
+        /// - Parameter mu: The prehashed message representative (a.k.a. "external mu").
+        ///
+        /// - Returns: The signature of the prehashed message representative.
+        func signature(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data {
+            try self.backing.signature(forPrehashedMessageRepresentative: mu)
+        }
+
         /// The size of the private key in bytes.
         static let byteCount = Backing.byteCount
 
@@ -184,6 +188,38 @@ extension MLDSA65 {
                 return signature
             }
 
+            /// Generate a signature for the prehashed message representative (a.k.a. "external mu").
+            ///
+            /// > Note: The message representative should be obtained via calls to ``MLDSA65/PublicKey/prehash(for:context:)``.
+            ///
+            /// - Parameter mu: The prehashed message representative (a.k.a. "external mu").
+            ///
+            /// - Returns: The signature of the prehashed message representative.
+            func signature(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data {
+                guard mu.count == MLDSA.muByteCount else {
+                    throw CryptoKitError.incorrectParameterSize
+                }
+
+                var signature = Data(repeating: 0, count: MLDSA65.signatureByteCount)
+
+                let rc: CInt = signature.withUnsafeMutableBytes { signaturePtr in
+                    let muBytes: ContiguousBytes = mu.regions.count == 1 ? mu.regions.first! : Array(mu)
+                    return muBytes.withUnsafeBytes { muPtr in
+                        CCryptoBoringSSL_MLDSA65_sign_message_representative(
+                            signaturePtr.baseAddress,
+                            &self.key,
+                            muPtr.baseAddress
+                        )
+                    }
+                }
+
+                guard rc == 1 else {
+                    throw CryptoKitError.internalBoringSSLError()
+                }
+
+                return signature
+            }
+
             /// The size of the private key in bytes.
             static let byteCount = Int(MLDSA65_PRIVATE_KEY_BYTES)
         }
@@ -242,6 +278,27 @@ extension MLDSA65 {
             self.backing.isValidSignature(signature, for: data, context: context)
         }
 
+        /// 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").
+        func prehash<D: DataProtocol>(for data: D) throws -> Data {
+            let context: Data? = nil
+            return try self.backing.prehash(for: data, context: context)
+        }
+
+        /// 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").
+        func prehash<D: DataProtocol, C: DataProtocol>(for data: D, context: C) throws -> Data {
+            try self.backing.prehash(for: data, context: context)
+        }
+
         /// The size of the public key in bytes.
         static let byteCount = Backing.byteCount
 
@@ -323,6 +380,41 @@ extension MLDSA65 {
                 }
             }
 
+            /// 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").
+            func prehash<D: DataProtocol, C: DataProtocol>(for data: D, context: C?) throws -> Data {
+                var mu = Data(repeating: 0, count: MLDSA.muByteCount)
+
+                let dataBytes: ContiguousBytes = data.regions.count == 1 ? data.regions.first! : Array(data)
+                let rc: CInt = mu.withUnsafeMutableBytes { muPtr in
+                    dataBytes.withUnsafeBytes { dataPtr in
+                        context.withUnsafeBytes { contextPtr in
+                            var prehash = MLDSA65_prehash()
+                            let rc = CCryptoBoringSSL_MLDSA65_prehash_init(
+                                &prehash,
+                                &key,
+                                contextPtr.baseAddress,
+                                contextPtr.count
+                            )
+                            CCryptoBoringSSL_MLDSA65_prehash_update(&prehash, dataPtr.baseAddress, dataPtr.count)
+                            CCryptoBoringSSL_MLDSA65_prehash_finalize(muPtr.baseAddress, &prehash)
+                            return rc
+                        }
+                    }
+                }
+
+                guard rc == 1 else {
+                    throw CryptoKitError.internalBoringSSLError()
+                }
+
+                return mu
+            }
+
             /// The size of the public key in bytes.
             static let byteCount = Int(MLDSA65_PUBLIC_KEY_BYTES)
         }
@@ -386,6 +478,17 @@ extension MLDSA87 {
             try self.backing.signature(for: data, context: context)
         }
 
+        /// 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.
+        func signature(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data {
+            try self.backing.signature(forPrehashedMessageRepresentative: mu)
+        }
+
         /// The size of the private key in bytes.
         static let byteCount = Backing.byteCount
 
@@ -486,6 +589,38 @@ extension MLDSA87 {
                 return signature
             }
 
+            /// 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.
+            func signature(forPrehashedMessageRepresentative mu: some DataProtocol) throws -> Data {
+                guard mu.count == MLDSA.muByteCount else {
+                    throw CryptoKitError.incorrectParameterSize
+                }
+
+                var signature = Data(repeating: 0, count: MLDSA87.signatureByteCount)
+
+                let rc: CInt = signature.withUnsafeMutableBytes { signaturePtr in
+                    let muBytes: ContiguousBytes = mu.regions.count == 1 ? mu.regions.first! : Array(mu)
+                    return muBytes.withUnsafeBytes { muPtr in
+                        CCryptoBoringSSL_MLDSA87_sign_message_representative(
+                            signaturePtr.baseAddress,
+                            &self.key,
+                            muPtr.baseAddress
+                        )
+                    }
+                }
+
+                guard rc == 1 else {
+                    throw CryptoKitError.internalBoringSSLError()
+                }
+
+                return signature
+            }
+
             /// The size of the private key in bytes.
             static let byteCount = Int(MLDSA87_PRIVATE_KEY_BYTES)
         }
@@ -544,6 +679,27 @@ extension MLDSA87 {
             self.backing.isValidSignature(signature, for: data, context: context)
         }
 
+        /// 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").
+        func prehash<D: DataProtocol>(for data: D) throws -> Data {
+            let context: Data? = nil
+            return try self.backing.prehash(for: data, context: context)
+        }
+
+        /// 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").
+        func prehash<D: DataProtocol, C: DataProtocol>(for data: D, context: C) throws -> Data {
+            try self.backing.prehash(for: data, context: context)
+        }
+
         /// The size of the public key in bytes.
         static let byteCount = Backing.byteCount
 
@@ -625,6 +781,41 @@ extension MLDSA87 {
                 }
             }
 
+            /// 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").
+            func prehash<D: DataProtocol, C: DataProtocol>(for data: D, context: C?) throws -> Data {
+                var mu = Data(repeating: 0, count: MLDSA.muByteCount)
+
+                let dataBytes: ContiguousBytes = data.regions.count == 1 ? data.regions.first! : Array(data)
+                let rc: CInt = mu.withUnsafeMutableBytes { muPtr in
+                    dataBytes.withUnsafeBytes { dataPtr in
+                        context.withUnsafeBytes { contextPtr in
+                            var prehash = MLDSA87_prehash()
+                            let rc = CCryptoBoringSSL_MLDSA87_prehash_init(
+                                &prehash,
+                                &key,
+                                contextPtr.baseAddress,
+                                contextPtr.count
+                            )
+                            CCryptoBoringSSL_MLDSA87_prehash_update(&prehash, dataPtr.baseAddress, dataPtr.count)
+                            CCryptoBoringSSL_MLDSA87_prehash_finalize(muPtr.baseAddress, &prehash)
+                            return rc
+                        }
+                    }
+                }
+
+                guard rc == 1 else {
+                    throw CryptoKitError.internalBoringSSLError()
+                }
+
+                return mu
+            }
+
             /// The size of the public key in bytes.
             static let byteCount = Int(MLDSA87_PUBLIC_KEY_BYTES)
         }
@@ -640,6 +831,9 @@ extension MLDSA87 {
 enum MLDSA {
     /// The size of the seed in bytes.
     static let seedByteCount = 32
+
+    /// The size of the "mu" value in bytes.
+    fileprivate static let muByteCount = 64
 }
 
 #endif  // CRYPTO_IN_SWIFTPM && !CRYPTO_IN_SWIFTPM_FORCE_BUILD_API