Add async * and - APIs (#251)

Author: fboemer

Snippets/HomomorphicEncryption/BasicsAsyncSnippet.swift

@@ -72,21 +72,21 @@ precondition(decoded == [7, 15, 2, 2, 11, 0, 7, 15])
 
 // snippet.subtraction
 // We can subtract a plaintext from a ciphertext.
-try sum -= plaintext
+try await 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
+try await 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
+try  await sum -= sum
 precondition(sum.isTransparent())
 
 // snippet.hide

Sources/HomomorphicEncryption/Ciphertext.swift

@@ -600,6 +600,8 @@ extension Collection {
 // MARK: - Async ciphertext functions
 
 extension Ciphertext {
+    // MARK: - Async ciphertext + plaintext
+
     /// Async ciphertext-plaintext addition.
     /// - Parameters:
     ///   - plaintext: Plaintext to add.
@@ -630,6 +632,22 @@ extension Ciphertext {
         return result
     }
 
+    /// Async ciphertext-plaintext addition.
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to add to.
+    ///   - plaintext: Plaintext to add.
+    /// - Throws: Error upon failure to add.
+    @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)
+    }
+
+    // MARK: - Async ciphertext + ciphertext
+
     /// Async ciphertext addition.
     /// - Parameters:
     ///   - lhs: Ciphertext to add to.
@@ -661,21 +679,189 @@ extension Ciphertext {
         return result
     }
 
-    /// Async ciphertext addition.
+    // MARK: Async ciphertext -= ciphertext
+
+    /// Async ciphertext subtraction.
     /// - Parameters:
-    ///   - ciphertext: Ciphertext to add to.
-    ///   - plaintext: Plaintext to add.
-    /// - Throws: Error upon failure to add.
-    /// - seealso: ``Ciphertext/+=(_:_:)-8y0jp`` for a sync version.
+    ///   - lhs: Ciphertext to subtract from.
+    ///   - rhs: Plaintext to subtract.
+    /// - Returns: A ciphertext encrypting the difference `lhs - rhs'.
+    /// - Throws: Error upon failure to subtract.
     @inlinable
-    public static func += (
+    public static func - (lhs: Ciphertext<Scheme, Format>,
+                          rhs: Ciphertext<Scheme, some PolyFormat>) async throws -> Self
+    {
+        var result = lhs
+        try await result -= rhs
+        return result
+    }
+
+    // MARK: Async ciphertext - ciphertext
+
+    /// Async ciphertext subtraction.
+    /// - Parameters:
+    ///   - lhs: Ciphertext to subtract from.
+    ///   - rhs: Ciphertext to subtract.
+    /// - Throws: Error upon failure to subtract.
+    @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.subAssignAsync(&lhs, rhs)
+    }
+
+    // MARK: Async ciphertext - plaintext
+
+    /// Async ciphertext - plaintext
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to subtract from.
+    ///   - plaintext: Plaintext to subtract.
+    /// - Returns: A ciphertext encrypting the difference `ciphertext - plaintext`.
+    /// - Throws: Error upon failure to subtract.
+    @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
+    }
+
+    // MARK: Async ciphertext -= plaintext
+
+    /// Async ciphertext -= plaintext
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to subtract from.
+    ///   - plaintext: Plaintext to subtract.
+    /// - Throws: Error upon failure to subtract.
+    @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)
+        try await Scheme.subAssignAsync(&ciphertext, plaintext)
+    }
+
+    // MARK: Async plaintext - ciphertext
+
+    /// Async plaintext - ciphertext.
+    /// - Parameters:
+    ///   - plaintext: Plaintext to subtract from.
+    ///   - ciphertext: Ciphertext to subtract.
+    /// - Returns: A ciphertext encrypting the difference `plaintext - ciphertext`.
+    /// - Throws: Error upon failure to subtract.
+    @inlinable
+    public static func - (
+        plaintext: Plaintext<Scheme, some PolyFormat>,
+        ciphertext: Ciphertext<Scheme, Format>) async throws -> Ciphertext<Scheme, Format>
+    {
+        try Scheme.validateEquality(of: ciphertext.context, and: plaintext.context)
+        return try await Scheme.subAsync(plaintext, ciphertext)
     }
 
+    // MARK: Async ciphertext * ciphertext
+
+    /// Async ciphertext multiplication.
+    /// - Parameters:
+    ///   - lhs: Ciphertext to multiply.
+    ///   - rhs: Ciphertext to multiply.
+    /// - Returns: A ciphertext encrypting the product `lhs * rhs`.
+    /// - Throws: Error upon failure to multiply.
+    /// > Note: the values of the decrypted product depend on the ``EncodeFormat`` of the plaintexts encrypted by `lhs`
+    /// and `rhs.`
+    ///
+    /// > Important: The resulting ciphertext has 3 polynomials and can be relinearized. See
+    /// ``HeScheme/relinearize(_:using:)``
+    @inlinable
+    public static func * (lhs: Ciphertext<Scheme, Format>, rhs: Ciphertext<Scheme, Format>) async throws -> Self
+        where Format == Scheme.CanonicalCiphertextFormat
+    {
+        var result = lhs
+        try await result *= rhs
+        return result
+    }
+
+    // MARK: Async ciphertext * plaintext
+
+    /// Async ciphertext-plaintext multiplication.
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to multiply.
+    ///   - plaintext: Plaintext to multiply.
+    /// - Returns: A ciphertext encrypting the product `ciphertext * plaintext`.
+    /// - Throws: Error upon failure to multiply.
+    @inlinable
+    public static func * (ciphertext: Ciphertext<Scheme, Format>,
+                          plaintext: Plaintext<Scheme, Eval>) async throws -> Self
+        where Format == Eval
+    {
+        var result = ciphertext
+        try await result *= plaintext
+        return result
+    }
+
+    /// Async ciphertext-plaintext multiplication.
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to multiply.
+    ///   - plaintext: Plaintext to multiply.
+    /// - Returns: A ciphertext encrypting the product `ciphertext * plaintext`.
+    /// - Throws: Error upon failure to multiply.
+    @inlinable
+    public static func * (plaintext: Plaintext<Scheme, Eval>,
+                          ciphertext: Ciphertext<Scheme, Format>) async throws -> Self
+        where Format == Eval
+    {
+        try await ciphertext * plaintext
+    }
+
+    // MARK: Async ciphertext *= plaintext
+
+    /// Async ciphertext-plaintext multiplication.
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to multiply. Will store the product.
+    ///   - plaintext: Plaintext to multiply.
+    /// - Throws: Error upon failure to multiply.
+    @inlinable
+    public static func *= (
+        ciphertext: inout Ciphertext<Scheme, Format>,
+        plaintext: Plaintext<Scheme, Eval>) async throws
+        where Format == Eval
+    {
+        try Scheme.validateEquality(of: ciphertext.context, and: plaintext.context)
+        try await Scheme.mulAssignAsync(&ciphertext, plaintext)
+    }
+
+    // MARK: Async ciphertext *= ciphertext
+
+    /// Async ciphertext-ciphertext multiplication.
+    /// - Parameters:
+    ///   - lhs: Ciphertext to multiply. Will store the product.
+    ///   - rhs: Ciphertext to multiply.
+    /// - Throws: Error upon failure to multiply.
+    @inlinable
+    public static func *= (lhs: inout Ciphertext<Scheme, Format>, rhs: Ciphertext<Scheme, Format>) async throws
+        where Format == Scheme.CanonicalCiphertextFormat
+    {
+        try Scheme.validateEquality(of: lhs.context, and: rhs.context)
+        try await Scheme.mulAssignAsync(&lhs, rhs)
+    }
+
+    // MARK: Async ciphertext = -ciphertext
+
+    /// Async ciphertext negation.
+    /// - Parameter ciphertext: Ciphertext to negate.
+    /// - Returns: The negated ciphertext.
+    @inlinable
+    public static prefix func - (_ ciphertext: Ciphertext<Scheme, Format>) async -> Self {
+        var result = ciphertext
+        await Scheme.negAssignAsync(&result)
+        return result
+    }
+
+    // MARK: - Async ciphertext format conversion
+
     /// Converts the ciphertext to coefficient format asynchronously.
     ///
     /// This method performs an asynchronous conversion of the ciphertext to ``Coeff`` format.

Sources/HomomorphicEncryption/HeSchemeAsync.swift

@@ -295,4 +295,122 @@ extension HeScheme {
         }
         // swiftlint:enable force_cast
     }
+
+    /// In-place ciphertext-plaintext subtraction: `ciphertext -= plaintext`.
+    ///
+    /// - Parameters:
+    ///   - ciphertext: Ciphertext to subtract from; will store the difference.
+    ///   - plaintext: Plaintext to subtract.
+    /// - Throws: Error upon failure to subtract.
+    /// - seealso: ``HeScheme/subAssign(_:_:)-5gs6p`` for a sync version.
+    @inlinable
+    public static func subAssignAsync<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 subAssignCoeffAsync(&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 subAssignEvalAsync(&evalCiphertext, plaintext as! EvalPlaintext)
+            ciphertext = evalCiphertext as! Ciphertext<Self, CiphertextFormat>
+        } else {
+            throw HeError.unsupportedHeOperation(
+                """
+                Subtraction between ciphertext in \(CiphertextFormat.description) \
+                and plaintext in \(PlaintextFormat.description).
+                """)
+        }
+        // swiftlint:enable force_cast
+    }
+
+    /// Plaintext-ciphertext subtraction: `plaintext - ciphertext`.
+    ///
+    /// - Parameters:
+    ///   - plaintext: Plaintext to subtract from.
+    ///   - ciphertext: Ciphertext to subtract.
+    /// - Returns: A ciphertext encrypting the difference.
+    /// - Throws: Error upon failure to subtract.
+    /// - seealso: ``HeScheme/sub(_:_:)-4xfo4`` for a sync version.
+    @inlinable
+    public static func subAsync<CiphertextFormat: PolyFormat, PlaintextFormat: PolyFormat>(
+        _ plaintext: Plaintext<Self, PlaintextFormat>,
+        _ ciphertext: Ciphertext<Self, CiphertextFormat>) async throws -> Ciphertext<Self, CiphertextFormat>
+    {
+        // swiftlint:disable force_cast
+        if CiphertextFormat.self == Coeff.self, PlaintextFormat.self == Coeff.self {
+            let coeffCiphertext = ciphertext as! CoeffCiphertext
+            let coeffPlaintext = plaintext as! CoeffPlaintext
+            return try await subCoeffAsync(coeffPlaintext, coeffCiphertext) as! Ciphertext<Self, CiphertextFormat>
+        }
+        if CiphertextFormat.self == Eval.self, PlaintextFormat.self == Eval.self {
+            let evalCiphertext = ciphertext as! EvalCiphertext
+            let evalPlaintext = plaintext as! EvalPlaintext
+            return try await subEvalAsync(evalPlaintext, evalCiphertext) as! Ciphertext<Self, CiphertextFormat>
+        }
+        throw HeError.unsupportedHeOperation("""
+            Subtraction between plaintext in \(PlaintextFormat.description) and \
+            ciphertext in \(CiphertextFormat.description).
+            """)
+        // swiftlint:enable force_cast
+    }
+
+    /// In-place ciphertext subtraction: `lhs -= rhs`.
+    ///
+    /// - Parameters:
+    ///   - lhs: Ciphertext to subtract from; will store the difference.
+    ///   - rhs: Ciphertext to subtract.
+    /// - Throws: Error upon failure to subtract.
+    /// - seealso: ``HeScheme/subAssign(_:_:)-75ktc`` for a sync version.
+    @inlinable
+    public static func subAssignAsync<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 subAssignCoeffAsync(&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 subAssignEvalAsync(&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
+    }
+
+    /// In-place ciphertext negation: `ciphertext = -ciphertext`.
+    ///
+    /// - Parameter ciphertext: Ciphertext to negate.
+    /// - seealso: ``HeScheme/negAssign(_:)`` for a sync version.
+    @inlinable
+    public static func negAssignAsync<Format: PolyFormat>(_ ciphertext: inout Ciphertext<Self, Format>) async {
+        // swiftlint:disable force_cast
+        if Format.self == Coeff.self {
+            var coeffCiphertext = ciphertext as! CoeffCiphertext
+            await negAssignCoeffAsync(&coeffCiphertext)
+            ciphertext = coeffCiphertext as! Ciphertext<Self, Format>
+        } else if Format.self == Eval.self {
+            var evalCiphertext = ciphertext as! EvalCiphertext
+            await negAssignEvalAsync(&evalCiphertext)
+            ciphertext = evalCiphertext as! Ciphertext<Self, Format>
+        } else {
+            fatalError("Unsupported Format \(Format.description)")
+        }
+        // swiftlint:enable force_cast
+    }
 }