Add SymmetricPIR key gen and documentation (#219)

Co-authored-by: Akshay Wadia <awadia@apple.com>

Author: akshaywadia

Sources/HomomorphicEncryption/Util.swift

@@ -12,6 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+import Foundation
 import ModularArithmetic
 
 extension Sequence where Element: Hashable {
@@ -70,6 +71,13 @@ extension [UInt8] {
     }
 }
 
+extension [UInt8] {
+    /// Hexadecimal encoded bytes.
+    public var hexString: String {
+        map { String(format: "%02x", $0) }.joined()
+    }
+}
+
 extension Array where Element: FixedWidthInteger {
     /// Computes the product of the elements in the array.
     ///

Sources/HomomorphicEncryption/Zeroization.swift

@@ -1,4 +1,4 @@
-// Copyright 2024 Apple Inc. and the Swift Homomorphic Encryption project authors
+// Copyright 2024-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.
@@ -15,16 +15,26 @@
 #if canImport(Darwin)
 import Darwin
 
+/// Set bytes to zero.
+/// - Parameters:
+///   - s: Pointer to memory region to be zeroed out.
+///   - n: Number of bytes to be zeroed out.
+@inlinable
 // swiftlint:disable:next implicitly_unwrapped_optional attributes
-@inlinable func zeroize(_ s: UnsafeMutableRawPointer!, _ n: Int) {
+public func zeroize(_ s: UnsafeMutableRawPointer!, _ n: Int) {
     let exitCode = memset_s(s, n, 0, n)
     precondition(exitCode == 0, "memset_s returned exit code \(exitCode)")
 }
 #else
 import CUtil
 
+/// Set bytes to zero.
+/// - Parameters:
+///   - s: Pointer to memory region to be zeroed out.
+///   - n: Number of bytes to be zeroed out.
+@inlinable
 // swiftlint:disable:next implicitly_unwrapped_optional attributes
-@inlinable func zeroize(_ s: UnsafeMutableRawPointer!, _ n: Int) {
+public func zeroize(_ s: UnsafeMutableRawPointer!, _ n: Int) {
     c_zeroize(s, n)
 }
 #endif

Sources/PIRProcessDatabase/PIRProcessDatabase.docc/PIRProcessDatabase.md

@@ -154,9 +154,35 @@ other usecase has 57 shards).
 Some PIR algorithms, such as MulPir, include an optimization which returns multiple keyword-value pairs in the PIR
 response, beyond the keyword-value pair requested by the client. However, this may be undesirable, e.g., if the database
 contains sensitive IP. `Symmetric PIR` is a variant of PIR which protects the unrequested server values from the client,
-in addition to the standard PIR guarantee protecting the client's keyword from the server. A best-effort approach
-towards enabling symmetric PIR is to pad the entries, such that only a limited number of entries are in the server
-response. However, this approach will increase server runtime.
+in addition to the standard PIR guarantee protecting the client's keyword from the server.
+
+There are two approaches to Symmetric PIR in Swift Homomorphic Encryption. The Fully Oblivious Symmetric PIR approach uses additional cryptographic primitives to guarantee that the client learns only the single keyword-value pair it requested, and is oblivious to other entries. The other is a best-effort approach that imposes an upper bound on the number of additional keyword-value pairs the client learns. We describe both these approaches next.
+
+##### Fully Oblivious Symmetric PIR
+
+In this approach, the server encrypts each keyword-value pair with a specific key derived from a single database encryption key. When querying, client first makes an extra call to the server, to learn information which would help it decrypt the entry it is interested in. Thus, this approach requires one additional call to the server.
+
+To process the database for Symmetric PIR, add the following to the configuration file.
+
+```json
+"symmetricPirArguments": {
+    "outputDatabaseEncryptionKeyFilePath": "path/to/output/key-file.txt"
+}
+```
+
+This will generate a fresh database encryption key, write it to `path/to/output/key-file.txt`, and use it for processing the database for Symmetric PIR.
+
+In case you want to use a database encryption key file that was generated earlier, you can specify the path in `databaseEncryptionKeyFilePath` instead, as follows.
+
+```json
+"symmetricPirArguments": {
+    "databaseEncryptionKeyFilePath": "path/to/key-file.txt"
+}
+```
+
+Note that only one of `outputDatabaseEncryptionKeyFilePath` and `databaseEncryptionKeyFilePath` should be present in the configuration.
+
+##### Best-Effort Symmetric PIR
 
 > Warning: This is only a best-effort approach, because HE does not guarantee *circuit privacy*.
 

Sources/PIRProcessDatabase/main.swift

@@ -13,6 +13,7 @@
 // limitations under the License.
 
 import ArgumentParser
+import Crypto
 import Foundation
 import HomomorphicEncryption
 import HomomorphicEncryptionProtobuf
@@ -36,23 +37,58 @@ enum TableSizeOption: Codable, Equatable, Hashable {
 /// The configuration for Symmetric PIR.
 struct SymmetricPirArguments: Codable, Hashable {
     /// File path for key with which database will be encrypted.
-    let databaseEncryptionKeyFilePath: String
+    ///
+    /// Also see ``outputDatabaseEncryptionKeyFilePath``.
+    let databaseEncryptionKeyFilePath: String?
     /// Config type for Symmetric PIR.
-    let configType: SymmetricPirConfigType
+    let configType: SymmetricPirConfigType?
+    /// Path to write newly generated database encryption key.
+    ///
+    /// If this is specified, a new database encryption key will be generated and written to this path.
+    /// This key will be used to encrypt the database for Symmetric PIR.
+    /// Exactly one of ``outputDatabaseEncryptionKeyFilePath`` or ``databaseEncryptionKeyFilePath`` should be present.
+    let outputDatabaseEncryptionKeyFilePath: String?
 
     /// Returns a parsed `SymmetricPirConfig` for given parameters.
     /// - Returns: Symmetric PIR config.
     func resolve() throws -> SymmetricPirConfig {
-        do {
-            let secretKeyString = try String(contentsOfFile: databaseEncryptionKeyFilePath, encoding: .utf8)
-            guard let secretKey = Array(hexEncoded: secretKeyString) else {
-                throw PirError.invalidOPRFHexSecretKey
+        if outputDatabaseEncryptionKeyFilePath != nil, databaseEncryptionKeyFilePath != nil {
+            throw ValidationError(
+                """
+                Both `databaseEncryptionKeyFilePath` and `outputDatabaseEncryptionKeyFilePath` \
+                can not be present in `symmetricPirArguments`.
+                """)
+        }
+        let configType = configType ?? .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128
+        if let databaseEncryptionKeyFilePath {
+            do {
+                let secretKeyString = try String(contentsOfFile: databaseEncryptionKeyFilePath, encoding: .utf8)
+                guard let secretKey = Array(hexEncoded: secretKeyString) else {
+                    throw PirError.invalidOPRFHexSecretKey
+                }
+                try configType.validateEncryptionKey(secretKey)
+                return try SymmetricPirConfig(oprfSecretKey: Secret(value: secretKey), configType: configType)
+            } catch {
+                throw PirError.failedToLoadOPRFKey(underlyingError: "\(error)", filePath: databaseEncryptionKeyFilePath)
+            }
+        }
+        if let outputDatabaseEncryptionKeyFilePath {
+            switch configType {
+            case .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128:
+                let secretKey = [UInt8](P384._VOPRF.PrivateKey().rawRepresentation)
+                try secretKey.hexString.write(
+                    toFile: outputDatabaseEncryptionKeyFilePath,
+                    atomically: true,
+                    encoding: .utf8)
+                return try SymmetricPirConfig(
+                    oprfSecretKey: Secret(value: secretKey), configType: .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128)
             }
-            try configType.validateEncryptionKey(secretKey)
-            return try SymmetricPirConfig(oprfSecretKey: secretKey, configType: configType)
-        } catch {
-            throw PirError.failedToLoadOPRFKey(underlyingError: "\(error)", filePath: databaseEncryptionKeyFilePath)
         }
+        throw ValidationError(
+            """
+            One of `databaseEncryptionKeyFilePath` or `outputDatabaseEncryptionKeyFilePath`\
+            should be present in `symmetricPirArguments`.
+            """)
     }
 }
 

Sources/PIRShardDatabase/ShardDatabase.swift

@@ -145,7 +145,7 @@ struct ProcessCommand: ParsableCommand {
                     throw PirError.invalidOPRFHexSecretKey
                 }
                 try configType.validateEncryptionKey(secretKey)
-                return try SymmetricPirConfig(oprfSecretKey: secretKey, configType: configType)
+                return try SymmetricPirConfig(oprfSecretKey: Secret(value: secretKey), configType: configType)
             } catch {
                 throw PirError.failedToLoadOPRFKey(underlyingError: "\(error)", filePath: filePath)
             }

Sources/PrivateInformationRetrieval/PrivateInformationRetrieval.docc/PrivateInformationRetrieval.md

@@ -14,8 +14,7 @@ While this *trivial PIR* protocol satisfies the privacy and correctness requirem
 
 The PIR implementation in Swift Homomorphic Encryption uses homomorphic encryption to improve upon the trivial PIR protocol.
 
-> Warning: PIR is asymmetric, meaning the client may learn keyword-value pairs not requested, as happens in trivial PIR for instance.
-> A variant of PIR, known as *symmetric PIR*, would be required to ensure the client does not learn anything about values it did not request.
+Note that PIR is asymmetric, meaning the client may learn keyword-value pairs not requested, as happens in trivial PIR for instance. Swift Homomorphic Encryption also implements *Symmetric PIR*, a variant of PIR which ensures the client does not learn anything about values it did not request.
 
 ## Topics
 <!-- Snippets are defined in a different "virtual module", requiring manually linking articles here. -->

Sources/PrivateInformationRetrieval/SymmetricPIRProtocol.swift

@@ -47,7 +47,7 @@ public struct OprfServer {
         guard case .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128 = symmetricPirConfig.configType else {
             throw PirError.invalidSymmetricPirConfig(symmetricPirConfig: symmetricPirConfig)
         }
-        self.oprfPrivateKey = try OprfPrivateKey(rawRepresentation: symmetricPirConfig.oprfSecretKey)
+        self.oprfPrivateKey = try OprfPrivateKey(rawRepresentation: symmetricPirConfig.oprfSecretKey.value)
     }
 
     /// Compute OPRF response.

Sources/PrivateInformationRetrieval/SymmetricPirDatabase.swift

@@ -94,10 +94,64 @@ public struct SymmetricPirClientConfig: Codable, Hashable, Sendable {
     }
 }
 
+/// A wrapper for secret values.
+public final class Secret: Equatable, Hashable, @unchecked Sendable {
+    /// Secret value bytes.
+    public var value: [UInt8]
+
+    @inlinable
+    public init(value: [UInt8]) {
+        self.value = value
+    }
+
+    public static func == (lhs: Secret, rhs: Secret) -> Bool {
+        lhs.value == rhs.value
+    }
+
+    public func hash(into hasher: inout Hasher) {
+        hasher.combine(value)
+    }
+
+    // Sets all bytes to zero.
+    @inlinable
+    public func zeroize() {
+        let zeroizeSize = value.count * MemoryLayout<UInt8>.size
+        value.withUnsafeMutableBytes { dataPointer in
+            // swiftlint:disable:next force_unwrapping
+            HomomorphicEncryption.zeroize(dataPointer.baseAddress!, zeroizeSize)
+        }
+    }
+
+    deinit {
+        zeroize()
+    }
+}
+
+extension Secret: Codable {
+    enum CodingKeys: String, CodingKey {
+        case value
+    }
+
+    public func encode(to encoder: any Encoder) throws {
+        var container = encoder.container(keyedBy: CodingKeys.self)
+        try container.encode("****", forKey: .value)
+    }
+}
+
+extension Secret: CustomStringConvertible, CustomDebugStringConvertible {
+    public var description: String {
+        "Secret(value: ****)"
+    }
+
+    public var debugDescription: String {
+        "Secret(value: ****)"
+    }
+}
+
 /// Configuration for Symmetric PIR.
 public struct SymmetricPirConfig: Codable, Hashable, Sendable {
     /// Secret key for keyword database encryption.
-    public let oprfSecretKey: [UInt8]
+    public let oprfSecretKey: Secret
     /// Symmetric PIR config type.
     public let configType: SymmetricPirConfigType
 
@@ -108,11 +162,11 @@ public struct SymmetricPirConfig: Codable, Hashable, Sendable {
     /// - Throws: Error on invalid key size.
     @inlinable
     public init(
-        oprfSecretKey: [UInt8],
+        oprfSecretKey: Secret,
         configType: SymmetricPirConfigType = .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128) throws
     {
-        guard oprfSecretKey.count == configType.oprfKeySize else {
-            throw PirError.invalidOPRFKeySize(oprfSecretKey.count, expectedSize: Int(configType.oprfKeySize))
+        guard oprfSecretKey.value.count == configType.oprfKeySize else {
+            throw PirError.invalidOPRFKeySize(oprfSecretKey.value.count, expectedSize: Int(configType.oprfKeySize))
         }
         self.oprfSecretKey = oprfSecretKey
         self.configType = configType
@@ -122,7 +176,7 @@ public struct SymmetricPirConfig: Codable, Hashable, Sendable {
     public func clientConfig() throws -> SymmetricPirClientConfig {
         switch configType {
         case .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128:
-            let serverPublicKey = try OprfPrivateKey(rawRepresentation: oprfSecretKey).publicKey
+            let serverPublicKey = try OprfPrivateKey(rawRepresentation: oprfSecretKey.value).publicKey
                 .oprfRepresentation
             return SymmetricPirClientConfig(serverPublicKey: [UInt8](serverPublicKey), configType: configType)
         }
@@ -142,7 +196,7 @@ extension KeywordDatabase {
         guard case .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128 = config.configType else {
             throw PirError.invalidSymmetricPirConfig(symmetricPirConfig: config)
         }
-        let oprfSecretKey = try OprfPrivateKey(rawRepresentation: config.oprfSecretKey)
+        let oprfSecretKey = try OprfPrivateKey(rawRepresentation: config.oprfSecretKey.value)
 
         return try database.map { entry in
             let oprfOutputHash = try [UInt8](oprfSecretKey.evaluate(Data(entry.keyword)))

Sources/TestUtilities/PirUtilities/SymmetricPirTests.swift

@@ -25,7 +25,7 @@ extension PirTestUtils {
         public static func generateSymmetricPirConfig() throws -> SymmetricPirConfig {
             let secretKey = [UInt8](OprfPrivateKey().rawRepresentation)
             return try SymmetricPirConfig(
-                oprfSecretKey: secretKey, configType: .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128)
+                oprfSecretKey: Secret(value: secretKey), configType: .OPRF_P384_AES_GCM_192_NONCE_96_TAG_128)
         }
 
         /// Tests symmetric PIR round trip.

Tests/PrivateInformationRetrievalTests/SymmetricPIRTests.swift

@@ -61,7 +61,7 @@ struct SymmetricPirTests {
             sharding: .shardCount(shardCount),
             symmetricPirConfig: config)
 
-        let oprfSecretKey = try OprfPrivateKey(rawRepresentation: config.oprfSecretKey)
+        let oprfSecretKey = try OprfPrivateKey(rawRepresentation: config.oprfSecretKey.value)
 
         let testIndex = Int.random(in: 0..<rowCount)
         let testKeyword = Data(testDatabase[testIndex].keyword)