apple/swift-homomorphic-encryption

# Swift 同态加密 *Swift 同态加密*（Swift Homomorphic Encryption）是同态加密（HE）及其应用（包括私密信息检索，Private Information Retrieval, PIR）的 Swift 实现。 Swift 同态加密的应用包括： * [实用来电 ID 查询](https://developer.apple.com/documentation/identitylookup/getting-up-to-date-calling-and-blocking-information-for-your-app) 与 [Network Extension URL 过滤器](https://developer.apple.com/documentation/networkextension/url-filters) * 有关示例服务，请参阅 [pir-service-example](https://github.com/apple/pir-service-example) ## 概述 Swift 同态加密是一系列库和可执行文件的集合。 有关更多信息，请参阅以下库的文档： * [HomomorphicEncryptionProtobuf](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/homomorphicencryptionprotobuf) * [HomomorphicEncryption](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/homomorphicencryption) * [ApplicationProtobuf](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/applicationprotobuf) * [PrivateInformationRetrieval](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/privateinformationretrieval) * [PrivateNearestNeighborSearch](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/privatenearestneighborsearch) 以及可执行文件： * [PIRGenerateDatabase](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/pirgeneratedatabase) * [PIRProcessDatabase](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/pirprocessdatabase) * [PIRShardDatabase](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/pirsharddatabase) * [PNNSGenerateDatabase](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/pnnsgeneratedatabase) * [PNNSProcessDatabase](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/main/documentation/pnnsprocessdatabase) 这些文档托管在 [Swift Package Index](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/documentation) 上。 ## 背景 ### 同态加密 (HE) Swift 同态加密实现了一种称为同态加密（HE）的特殊密码学形式。 HE 是一种允许对加密数据进行计算的密码系统。 计算直接在加密数据上执行，*而不会向执行操作的进程泄露该数据的明文*。 因此，HE 的计算过程不需要解密或使用解密密钥。 由此，HE 允许客户端授权服务器对加密数据执行操作，从而不会向服务器泄露数据。 典型的 HE 工作流程可能如下： * 客户端对其敏感数据进行加密，并将生成的密文发送给服务器。 * 服务器对该密文（以及可能的服务器自身明文输入）执行 HE 计算，而无法获知任何密文解密后的内容。 * 服务器将计算生成的密文响应发送给客户端。 * 客户端进行解密以获取响应结果。 Swift 同态加密实现了 Brakerski-Fan-Vercauteren (BFV) HE 方案，该方案基于带误差环学习（Ring Learning With Errors, RLWE）困难问题。 该方案可配置为支持后量子 128 位安全性。 ### 私密信息检索 (PIR) 私密信息检索（PIR）是 HE 的一项应用。 PIR 允许客户端从托管“关键字-值”（keyword-value）数据库的服务器上执行数据库查询，*而服务器无法获知客户端查询中使用的关键字。* 数据库中的每一行都是一个*关键字*（keyword）以及与之关联的*值*（value）。 在 PIR 协议执行期间，客户端使用其私有关键字发出查询，并获取与该关键字关联的值。 PIR 的一种简单实现是让客户端发出一个通用的“获取数据库”请求，该请求与其私有关键字无关。 随后，服务器将整个数据库发送给客户端。 虽然这种*平凡 PIR（trivial PIR）*协议满足了 PIR 的隐私和正确性要求，但它仅适用于小型数据库。 Swift 同态加密中的 PIR 实现利用 HE 对平凡 PIR 协议进行了改进。 ### 私密最近邻搜索 (PNNS) 私密最近邻搜索（PNNS）允许拥有私有向量的客户端，在服务器托管的数据库中搜索最近的向量，*而服务器无法获知客户端的向量。* 数据库中的每一行都是一个*向量*，以及与之关联的*条目标识符*（entry identifier）和*条目元数据*（entry metadata）。 在 PNNS 协议执行期间，客户端使用其私有向量发出查询，并根据 ``DistanceMetric`` 获知最近邻。 具体而言，客户端将获知客户端查询向量与最近邻之间的距离，以及该最近邻的条目标识符和条目元数据。 PNNS 的一种简单实现是让客户端发出一个通用的“获取数据库”请求，该请求与其私有向量无关。 随后，服务器将整个数据库发送给客户端，由客户端在本地计算距离。 虽然这种*平凡 PNNS（trivial PNNS）*协议满足了 PNNS 的隐私和正确性要求，但它仅适用于小型数据库。 Swift 同态加密中的 PNNS 实现利用同态加密对平凡 PNNS 协议进行了改进。 ## 使用 Swift 同态加密 Swift 同态加密以 Swift Package Manager 包的形式提供。 要使用 Swift 同态加密，请选择一个 [标签](https://github.com/apple/swift-homomorphic-encryption/tags)。 然后，在你的 `Package.swift` 中添加以下依赖项 ``` .package( url: "https://github.com/apple/swift-homomorphic-encryption", from: "tag"), ``` ，将 `tag` 替换为你选择的标签，例如 `1.0.0`。 要使用 `HomomorphicEncryption` 库，请添加 ``` .product(name: "HomomorphicEncryption", package: "swift-homomorphic-encryption"), ``` 到你的 target 的依赖项中。 然后，你可以添加 ``` import HomomorphicEncryption ``` 到你的 Swift 代码中，以访问 `HomomorphicEncryption` 库中的功能。 #### 示例 有关使用 `HomomorphicEncryption` 的示例，请参阅 [Snippets](https://github.com/apple/swift-homomorphic-encryption/tree/main/Snippets)。 要列出可用的代码片段， ``` swift package show-executables | grep 'Snippet' ``` 要运行 `EncryptionParametersSnippet`，请运行 ``` swift run -c release EncryptionParametersSnippet ``` ### 支持的平台 Swift 同态加密旨在支持所有支持 Swift 的平台。 ### Swift / Xcode 版本 下表列出了 Swift 同态加密包版本与所需的 Swift 及 Xcode 版本之间的对应关系： 包版本 | Swift 版本 | Xcode 版本 ----------------|---------------|----------------------------------------- 1.0.x | >= Swift 5.10 | >= Xcode 15.3 main | >= Swift 6.2 | >= Xcode 26 ### 源码稳定性 Swift 同态加密遵循 [语义化版本 2.0.0](https://semver.org/spec/v2.0.0.html)。对公共 API 的破坏性源码更改只能在一个新的主版本中进行，但以下情况除外： * 向公共 `enum` 类型添加新的 `case` 只需要提升次要版本号。例如，我们可能会向 [HeError](https://swiftpackageindex.com/apple/swift-homomorphic-encryption/documentation/homomorphicencryption/heerror) 添加一个新的 `enum`。为了避免破坏源代码，在对 enum 值添加 `switch` 时，请添加 `default` case。 该包未来的次要版本可能会根据需要对这些规则进行更改。 我们希望这个包能够迅速采用与其目标相关的 Swift 语言和工具链改进。因此，我们预计该包的新版本将不时要求客户端升级到更新的 Swift 工具链版本。要求使用新的 Swift 版本仅需要提升次要版本号。 ## 开发 Swift 同态加密 ### 依赖项 开发 Swift 同态加密需要： * [Nick Lockwood SwiftFormat](https://github.com/nicklockwood/SwiftFormat), 0.60.0 * [pre-commit](https://pre-commit.com) * [swift-format](https://github.com/swiftlang/swift-format), 602.0.0 * [swift-protobuf](https://github.com/apple/swift-protobuf), 1.31.1 * [SwiftLint](https://github.com/realm/SwiftLint), 0.63.2 ### 构建 你可以通过 Xcode 或在终端的命令行中构建 Swift 同态加密。 克隆仓库后，运行 ``` cd swift-homomorphic-encryption git submodule update --init --recursive ``` #### Xcode 要在 Xcode 中构建 Swift 同态加密，只需在 Xcode 中打开根目录即可。 有关使用 Xcode 进行开发的更多详细信息，请参阅 [Xcode 文档](https://developer.apple.com/documentation/Xcode)。 #### 命令行 要在命令行中构建 Swift 同态加密，请在终端中打开克隆仓库的根目录（即 `swift-homomorphic-encryption` 目录），并运行 ``` swift build -c release ``` 构建产物将位于 `.build/release/` 文件夹中。 要在 debug 模式下构建，请运行 ``` swift build ``` 构建产物将位于 `.build/debug/` 文件夹中。 ### 安装 要安装 Swift 同态加密的 targets，请使用 Swift Package Manager 的 `experimental-install` 功能。 首先，请确保 `~/.swiftpm/bin` 目录包含在你的 `$PATH` 中。 例如，如果你使用的是 `zsh` shell，请将以下行添加到你的 `~/.zshrc` 中 ``` export PATH="$HOME/.swiftpm/bin:$PATH" ``` 确保通过（`source ~/.zshrc`）或重启你的终端模拟器来重新加载路径。 然后，要安装 `PIRProcessDatabase` 可执行文件，例如，请运行 ``` swift package experimental-install -c release --product PIRProcessDatabase ``` ### 测试 通过以下命令运行单元测试 ``` swift test -c release ``` 要在 debug 模式下运行测试，请运行 ``` swift test ``` ### 基准测试 Swift 同态加密使用 [Benchmark](https://github.com/ordo-one/package-benchmark) 进行基准测试。 要启用基准测试，请设置环境变量 `SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_BENCHMARKING=1`。 默认情况下，基准测试需要 [jemalloc](http://jemalloc.net) 依赖项。 运行基准测试的两种方式是： * Xcode * 在 Xcode 中打开 `swift-homomorphic-encryption` 文件夹并设置 `SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_BENCHMARKING=1`，例如： * `open --env SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_BENCHMARKING=1 Package.swift` * 切换到 benchmark target。 * 运行该 target，例如，通过 `Product` 菜单。 * 命令行 * 运行 `SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_BENCHMARKING=1 swift package benchmark`。 * 有关运行基准测试的更多信息，请参阅 [Benchmark](https://github.com/ordo-one/package-benchmark) 文档。 # 文档 Swift 同态加密使用 DocC 生成文档。 有关更多信息，请参阅 [DocC 文档](https://www.swift.org/documentation/docc) 和 [Swift-DocC Plugin](https://swiftlang.github.io/swift-docc-plugin/documentation/swiftdoccplugin/)。 ## Xcode 可以通过 Xcode 的 `Product -> Build Documentation` 来构建文档。 ## 命令行 可以通过运行以下命令从命令行构建文档 ``` SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_DOCCPLUGIN=1 swift package generate-documentation ``` 并通过运行以下命令进行预览 ``` SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_DOCCPLUGIN=1 swift package --disable-sandbox preview-documentation --target HomomorphicEncryption ```

标签：Swift, 同态加密, 密码学库, 私有信息检索, 网络安全, 隐私保护