Add async + and += APIs (#250)

Author: fboemer

Snippets/HomomorphicEncryption/BasicsAsyncSnippet.swift

@@ -0,0 +1,95 @@
+// Example showing the basics with async APIs.
+
+// snippet.hide
+// Copyright 2025 Apple Inc. and the Swift Homomorphic Encryption project authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+// snippet.show
+
+// snippet.encryption
+import HomomorphicEncryption
+
+// snippet.hide
+// swiftformat:disable:all
+func main() async throws {
+// snippet.show
+
+// We start by choosing some encryption parameters for the Bfv<UInt64> scheme.
+// *These encryption parameters are insecure, suitable for testing only.*
+let encryptParams =
+    try EncryptionParameters<UInt64>(from: .insecure_n_8_logq_5x18_logt_5)
+// Perform pre-computation for HE computation with these parameters.
+let context = try Context<Bfv<UInt64>>(encryptionParameters: encryptParams)
+
+// We encode N values using coefficient encoding.
+// Operations on sensitive data like unencrypted values remain synchronous.
+let values: [UInt64] = [8, 5, 12, 12, 15, 0, 8, 5]
+let plaintext: Bfv<UInt64>.CoeffPlaintext = try context.encode(
+    values: values,
+    format: .coefficient)
+
+// We generate a secret key and use it to encrypt the plaintext.
+let secretKey = try context.generateSecretKey()
+let ciphertext = try plaintext.encrypt(using: secretKey)
+
+// Decrypting the plaintext yields the original values.
+let decrypted = try ciphertext.decrypt(using: secretKey)
+var decoded: [UInt64] = try decrypted.decode(format: .coefficient)
+precondition(decoded == values)
+
+// Mixing formats between encoding and decoding yields incorrect results.
+decoded = try decrypted.decode(format: .simd)
+precondition(decoded != values)
+
+// snippet.addition
+// We add the ciphertext with the plaintext, yielding another ciphertext.
+// The `await` keyword indicates this is an asynchronous operation.
+var sum = try await ciphertext + plaintext
+
+// The ciphertext decrypts to the element-wise sum of the ciphertext's
+// and plaintext's values, mod 17, the plaintext modulus.
+precondition(encryptParams.plaintextModulus == 17)
+var plaintextSum = try sum.decrypt(using: secretKey)
+decoded = try plaintextSum.decode(format: .coefficient)
+precondition(decoded == [16, 10, 7, 7, 13, 0, 16, 10])
+
+// We can also add ciphertexts.
+try await sum += ciphertext
+plaintextSum = try sum.decrypt(using: secretKey)
+decoded = try plaintextSum.decode(format: .coefficient)
+precondition(decoded == [7, 15, 2, 2, 11, 0, 7, 15])
+// snippet.end
+
+// snippet.subtraction
+// We can subtract a plaintext from a ciphertext.
+try sum -= plaintext
+plaintextSum = try sum.decrypt(using: secretKey)
+decoded = try plaintextSum.decode(format: .coefficient)
+precondition(decoded == [16, 10, 7, 7, 13, 0, 16, 10])
+
+// We can also subtract a ciphertext from a ciphertext.
+try sum -= ciphertext
+plaintextSum = try sum.decrypt(using: secretKey)
+decoded = try plaintextSum.decode(format: .coefficient)
+precondition(decoded == [8, 5, 12, 12, 15, 0, 8, 5])
+
+// One special case is when subtracting a ciphertext from itself.
+// This yields a "transparent ciphertext", which reveals the underlying
+// plaintext to any observer. The observed value in this case is zero.
+try sum -= sum
+precondition(sum.isTransparent())
+
+// snippet.hide
+}
+try await main()
+// snippet.show

Sources/HomomorphicEncryption/Ciphertext.swift

@@ -373,6 +373,7 @@ extension Ciphertext {
     ///   - plaintext: Plaintext to add.
     /// - Returns: A ciphertext encrypting the sum.
     /// - Throws: Error upon failure to add.
+    /// - seealso: ``Ciphertext/+(_:_:)-3mot4`` for an async version.
     @inlinable
     public static func + (ciphertext: Ciphertext<Scheme, Format>,
                           plaintext: Plaintext<Scheme, some PolyFormat>) throws -> Self
@@ -388,6 +389,7 @@ extension Ciphertext {
     ///   - ciphertext: Ciphertext to add.
     /// - Returns: A ciphertext encrypting the sum.
     /// - Throws: Error upon failure to add.
+    /// - seealso: ``Ciphertext/+(_:_:)-3hq92`` for an async version.
     @inlinable
     public static func + (plaintext: Plaintext<Scheme, some PolyFormat>,
                           ciphertext: Ciphertext<Scheme, Format>) throws -> Self
@@ -420,6 +422,7 @@ extension Ciphertext {
     ///   - rhs: Plaintext to add.
     /// - Returns: A ciphertext encrypting the sum `lhs + rhs'.
     /// - Throws: Error upon failure to add.
+    /// - seealso: ``Ciphertext/+(_:_:)-89dia`` for an async version.
     @inlinable
     public static func + (lhs: Ciphertext<Scheme, Format>, rhs: Ciphertext<Scheme, some PolyFormat>) throws -> Self {
         var result = lhs
@@ -595,8 +598,85 @@ extension Collection {
     }
 }
 
-/// Async ciphertext functions.
+// MARK: - Async ciphertext functions
+
 extension Ciphertext {
+    /// Async ciphertext-plaintext addition.
+    /// - Parameters:
+    ///   - plaintext: Plaintext to add.
+    ///   - ciphertext: Ciphertext to add.
+    /// - Returns: A ciphertext encrypting the sum.
+    /// - Throws: Error upon failure to add.
+    /// - seealso: ``Ciphertext/+(_:_:)-2g1nj`` for a sync version.
+    @inlinable
+    public static func + (plaintext: Plaintext<Scheme, some PolyFormat>,
+                          ciphertext: Ciphertext<Scheme, Format>) async throws -> Self
+    {
+        try await ciphertext + plaintext
+    }
+
+    /// Async ciphertext-plaintext addition.
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to add.
+    ///   - plaintext: Plaintext to add.
+    /// - Returns: A ciphertext encrypting the sum.
+    /// - Throws: Error upon failure to add.
+    /// - seealso: ``Ciphertext/+(_:_:)-42x1k`` for a sync version.
+    @inlinable
+    public static func + (ciphertext: Ciphertext<Scheme, Format>,
+                          plaintext: Plaintext<Scheme, some PolyFormat>) async throws -> Self
+    {
+        var result = ciphertext
+        try await result += plaintext
+        return result
+    }
+
+    /// Async ciphertext addition.
+    /// - Parameters:
+    ///   - lhs: Ciphertext to add to.
+    ///   - rhs: Ciphertext to add.
+    /// - Throws: Error upon failure to add.
+    /// - seealso: ``Ciphertext/+=(_:_:)-49um`` for a sync version.
+    @inlinable
+    public static func += (
+        lhs: inout Ciphertext<Scheme, Format>,
+        rhs: Ciphertext<Scheme, some PolyFormat>) async throws
+    {
+        try Scheme.validateEquality(of: lhs.context, and: rhs.context)
+        try await Scheme.addAssignAsync(&lhs, rhs)
+    }
+
+    /// Async ciphertext addition.
+    /// - Parameters:
+    ///   - lhs: Ciphertext to add.
+    ///   - rhs: Ciphertext to add.
+    /// - Returns: A ciphertext encrypting the sum `lhs + rhs'.
+    /// - Throws: Error upon failure to add.
+    /// - seealso: ``Ciphertext/+(_:_:)-2jflc`` for a sync version.
+    @inlinable
+    public static func + (lhs: Ciphertext<Scheme, Format>,
+                          rhs: Ciphertext<Scheme, some PolyFormat>) async throws -> Self
+    {
+        var result = lhs
+        try await result += rhs
+        return result
+    }
+
+    /// Async ciphertext addition.
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to add to.
+    ///   - plaintext: Plaintext to add.
+    /// - Throws: Error upon failure to add.
+    /// - seealso: ``Ciphertext/+=(_:_:)-8y0jp`` for a sync version.
+    @inlinable
+    public static func += (
+        ciphertext: inout Ciphertext<Scheme, Format>,
+        plaintext: Plaintext<Scheme, some PolyFormat>) async throws
+    {
+        try Scheme.validateEquality(of: ciphertext.context, and: plaintext.context)
+        try await Scheme.addAssignAsync(&ciphertext, plaintext)
+    }
+
     /// Converts the ciphertext to coefficient format asynchronously.
     ///
     /// This method performs an asynchronous conversion of the ciphertext to ``Coeff`` format.

Sources/HomomorphicEncryption/HeSchemeAsync.swift

@@ -226,3 +226,73 @@ extension HeScheme {
     }
     // swiftlint:enable missing_docs
 }
+
+// MARK: - Implementations generalized over PolyFormat
+
+extension HeScheme {
+    /// In-place ciphertext-plaintext addition: `ciphertext += plaintext`.
+    ///
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to add; will store the sum.
+    ///   - plaintext: Plaintext to add.
+    /// - Throws: Error upon failure to add.
+    /// - seealso: ``HeScheme/addAssign(_:_:)-407pg`` for a sync version.
+    @inlinable
+    public static func addAssignAsync<CiphertextFormat: PolyFormat, PlaintextFormat: PolyFormat>(
+        _ ciphertext: inout Ciphertext<Self, CiphertextFormat>,
+        _ plaintext: Plaintext<Self, PlaintextFormat>) async throws
+    {
+        // swiftlint:disable force_cast
+        if CiphertextFormat.self == Coeff.self, PlaintextFormat.self == Coeff.self {
+            var coeffCiphertext = ciphertext as! CoeffCiphertext
+            try await addAssignCoeffAsync(&coeffCiphertext, plaintext as! CoeffPlaintext)
+            ciphertext = coeffCiphertext as! Ciphertext<Self, CiphertextFormat>
+        } else if CiphertextFormat.self == Eval.self, PlaintextFormat.self == Eval.self {
+            var evalCiphertext = ciphertext as! EvalCiphertext
+            try await addAssignEvalAsync(&evalCiphertext, plaintext as! EvalPlaintext)
+            ciphertext = evalCiphertext as! Ciphertext<Self, CiphertextFormat>
+        } else {
+            throw HeError.unsupportedHeOperation(
+                """
+                Addition between ciphertext in \(CiphertextFormat.description) \
+                and plaintext in \(PlaintextFormat.description).
+                """)
+        }
+        // swiftlint:enable force_cast
+    }
+
+    /// In-place ciphertext addition: `lhs += rhs`.
+    ///
+    /// - Parameters:
+    ///   - lhs: Ciphertext to add; will store the sum.
+    ///   - rhs: Ciphertext to add.
+    /// - Throws: Error upon failure to add.
+    /// - seealso: ``HeScheme/addAssign(_:_:)-1sd4b`` for a sync version.
+    @inlinable
+    public static func addAssignAsync<LhsFormat: PolyFormat, RhsFormat: PolyFormat>(
+        _ lhs: inout Ciphertext<Self, LhsFormat>,
+        _ rhs: Ciphertext<Self, RhsFormat>) async throws
+    {
+        // swiftlint:disable force_cast
+        if LhsFormat.self == Coeff.self {
+            var lhsCoeffCiphertext = lhs as! CoeffCiphertext
+            if RhsFormat.self == Coeff.self {
+                try await addAssignCoeffAsync(&lhsCoeffCiphertext, rhs as! CoeffCiphertext)
+            } else {
+                fatalError("Unsupported Format \(RhsFormat.description)")
+            }
+            lhs = lhsCoeffCiphertext as! Ciphertext<Self, LhsFormat>
+        } else if LhsFormat.self == Eval.self {
+            var lhsEvalCiphertext = lhs as! EvalCiphertext
+            if RhsFormat.self == Eval.self {
+                try await addAssignEvalAsync(&lhsEvalCiphertext, rhs as! EvalCiphertext)
+            } else {
+                fatalError("Unsupported Format \(RhsFormat.description)")
+            }
+            lhs = lhsEvalCiphertext as! Ciphertext<Self, LhsFormat>
+        } else {
+            fatalError("Unsupported Format \(LhsFormat.description)")
+        }
+        // swiftlint:enable force_cast
+    }
+}

Sources/HomomorphicEncryption/HomomorphicEncryption.docc/Examples.md

@@ -6,6 +6,9 @@ Examples for how to use ``HomomorphicEncryption``
 We start with the basics.
 @Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/BasicsSnippet", slice:"encryption")
 
+We also have async APIs.
+@Snippet(path: "swift-homomorphic-encryption/Snippets/HomomorphicEncryption/BasicsAsyncSnippet", slice:"encryption")
+
 ### HE Addition and Subtraction
 Continuing from the previous example, we can also compute on the encrypted data.
 We can add a ciphertext with a ciphertext or a plaintext.