Swift 同态加密

Swift 同态加密 是同态加密（HE）及其应用的 Swift 实现，其中包括私有信息检索（PIR）。

Swift 同态加密的应用包括：

• 实时来电显示查询 & 网络扩展 URL 过滤器
  • 参见 pir-service-example 获取示例服务

概述

Swift 同态加密是一组库和可执行文件的集合。 有关更多信息，请参阅库的文档：

• HomomorphicEncryptionProtobuf
• HomomorphicEncryption
• ApplicationProtobuf
• PrivateInformationRetrieval
• PrivateNearestNeighborSearch

以及可执行文件：

• PIRGenerateDatabase
• PIRProcessDatabase
• PIRShardDatabase
• PNNSGenerateDatabase
• PNNSProcessDatabase

文档托管在 Swift Package Index 上。

背景

同态加密 (HE)

Swift 同态加密实现了一种称为同态加密（HE）的特殊形式的密码学。 HE 是一种允许对加密数据进行计算的密码系统。 计算直接在加密数据上执行，而不会向处理进程揭示该数据的明文。 因此，HE 计算在没有解密或访问解密密钥的情况下进行。

HE 由此允许客户端使服务器能够对加密数据执行操作，从而在不向服务器泄露数据的情况下完成这些操作。 典型的 HE 工作流程可能如下：

• 客户端加密其敏感数据，并将生成的密文发送到服务器。
• 服务器对密文执行 HE 计算（可能还包括其自身的明文输入），而不会得知任何密文解密后的内容。
• 服务器将生成的密文响应发送回客户端。
• 客户端解密以获取响应。

Swift Homomorphic Encryption 实现了 Brakerski-Fan-Vercauteren (BFV) HE 方案，该方案基于环学习带误差 (RLWE) 困难问题。 该方案可配置为支持后量子 128 位安全性。

[!WARNING] BFV 不提供 IND-CCA 安全性，当存在不可忽略的解密错误概率时，也不提供 IND-CPA^D 安全性。应相应地使用 BFV。 因此，不应将有关每个解密后密文的信息发送回服务器。 特别是，密文的噪声预算（通过 noiseBudget 计算）不得转发给任何其他方。 共享解密后的密文或噪声预算相当于一个预言机，可用于恢复秘密密钥。 为了防范恶意服务器，客户端还应验证解密后的内容是否符合预期格式。

在开发和部署同态加密应用时，请咨询密码学专家。

私有信息检索 (PIR)

私有信息检索 (PIR) 是 HE 的一种应用。 PIR 允许客户端从托管关键字-值数据库的服务器执行数据库查找，且服务器不会获知客户端查询中的关键字。 数据库中的每一行都是一个关键字及其关联的值。 在 PIR 协议期间，客户端使用其私有关键字发出查询，并获知与该关键字关联的值。

PIR 的一种平凡实现是让客户端发出通用的“获取数据库”请求，该请求与其私有关键字无关。 然后服务器将整个数据库发送给客户端。 虽然这种平凡 PIR 协议满足了 PIR 的隐私和正确性要求，但它仅适用于小型数据库。

Swift Homomorphic Encryption 中的 PIR 实现使用 HE 来改进平凡 PIR 协议。

[!WARNING] PIR 是非对称的，这意味着客户端可能会获知未请求的关键字-值对，例如在平凡 PIR 中发生的情况。 需要 PIR 的一种变体，称为对称 PIR，以确保客户端不会获知其未请求的任何值的信息。

私有最近邻搜索 (PNNS)

私有最近邻搜索 (PNNS) 允许拥有私有向量的客户端在由服务器托管的数据库中搜索最近的向量，且服务器无法获知客户端的向量。 数据库中的每一行都是一个向量，并关联有条目标识符和条目元数据。 在 PNNS 协议期间，客户端使用其私有向量发出查询，并根据 DistanceMetric 学习最近邻。 具体而言，客户端学习其查询向量与最近邻之间的距离，以及最近邻的条目标识符和条目元数据。

PNNS 的一种平凡实现是让客户端发出通用的“获取数据库”请求，该请求与其私有向量无关。 然后，服务器将整个数据库发送给客户端，由客户端在本地计算距离。 虽然这种平凡 PNNS 协议满足 PNNS 的隐私和正确性要求，但它仅适用于小型数据库。

Swift Homomorphic Encryption 中的 PNNS 实现使用同态加密来改进平凡 PNNS 协议。

使用 Swift Homomorphic Encryption

Swift Homomorphic Encryption 可作为 Swift Package Manager 包使用。 要使用 Swift Homomorphic Encryption，请选择一个 tag。 然后，在您的 Package.swift 中添加以下依赖项

.package(
    url: "https://github.com/apple/swift-homomorphic-encryption",
    from: "tag"),

，将 tag 替换为您选择的 tag，例如 1.0.0。

要使用 HomomorphicEncryption 库，请将

.product(name: "HomomorphicEncryption", package: "swift-homomorphic-encryption"),

添加到您的目标依赖项中。

[!IMPORTANT] 在链接可执行文件时，请确保设置 -cross-module-optimization。 如果没有此标志，Swift Homomorphic Encryption 的性能会严重下降， 原因是未能特化泛型。例如，

.executableTarget(
   name: "YourTarget",
   dependencies: [
       .product(name: "HomomorphicEncryption", package: "swift-homomorphic-encryption"),
   ],
   swiftSettings: [.unsafeFlags(["-cross-module-optimization"],
      .when(configuration: .release))]
)

然后你可以添加

 import HomomorphicEncryption

到你的 Swift 代码中，以访问 HomomorphicEncryption 库中的功能。

[!NOTE] 如果你正在使用 Swift Homomorphic Encryption 进行研究，请使用 CITATION.cff 文件进行引用。

示例

请参阅 Snippets 以查看使用 HomomorphicEncryption 的示例。 要列出可用的 snippets，

swift package show-executables | grep 'Snippet'

要运行 EncryptionParametersSnippet，请执行

swift run -c release EncryptionParametersSnippet

[!NOTE] 你可能会收到一个错误，提示未找到测试框架，例如 dyld[12358]: Library not loaded: @rpath/Testing.framework/Versions/A/Testing。 要在 macOS 上修复此问题，请尝试以下变通方法之一，并根据需要替换 /Applications/Xcode.app。

• DYLD_INSERT_LIBRARIES=/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Frameworks/Testing.framework/Versions/A/Testing swift run -c release EncryptionParametersSnippet
• swift run -Xlinker -rpath -Xlinker /Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/Library/Frameworks/ -c release EncryptionParametersSnippet

支持的平台

Swift Homomorphic Encryption 旨在支持所有 Swift 支持的平台。

[!NOTE] Swift Homomorphic Encryption 依赖 SystemRandomNumberGenerator 作为密码学安全的随机数生成器，其行为可能因平台而异。

Swift / Xcode 版本

下表将 Swift Homomorphic Encryption 包版本映射到所需的 Swift 和 Xcode 版本：

Package version	Swift version	Xcode version
1.0.x	>= Swift 5.10	>= Xcode 15.3
main	>= Swift 6.2	>= Xcode 26

源码稳定性

Swift Homomorphic Encryption 遵循 语义化版本 2.0.0。对公共 API 的源码破坏性变更只能出现在新的主版本中，但有以下例外：

• 向公共 enum 类型添加新的 case 仅需提升次版本号。例如，我们可能会向 HeError 添加新的 enum。为避免破坏源码，在枚举值上添加 switch 时，请添加一个 default 情况。

该包未来的次版本可能会根据需要引入对这些规则的变更。

我们希望该包能够迅速采纳与其职责相关的 Swift 语言和工具链改进。因此，我们预计该包的新版本有时会要求客户端升级到更新的 Swift 工具链版本。要求新的 Swift 版本仅需提升次版本号。

[!WARNING] 以下划线开头的任何符号，以及以下划线开头的任何产品，均不受语义化版本控制：这些 API 可能会在没有警告的情况下发生变更。

开发 Swift Homomorphic Encryption

依赖项

开发 Swift Homomorphic Encryption 需要：

• Nick Lockwood SwiftFormat, 0.60.0
• pre-commit
• swift-format, 602.0.0
• swift-protobuf, 1.31.1
• SwiftLint, 0.63.2

构建

您可以通过 Xcode 或终端中的命令行来构建 Swift Homomorphic Encryption。

克隆仓库后，运行

cd swift-homomorphic-encryption
git submodule update --init --recursive

Xcode

要从 Xcode 构建 Swift Homomorphic Encryption，只需在 Xcode 中打开根目录。 有关使用 Xcode 进行开发的更多详细信息，请参阅 Xcode 文档。

Command line

要从命令行构建 Swift Homomorphic Encryption，请在终端中打开克隆仓库的根目录（即 swift-homomorphic-encryption 目录），并运行

swift build -c release

构建产物将位于 .build/release/ 文件夹中。

要以调试模式构建，请运行

swift build

构建产物将位于 .build/debug/ 文件夹中。

[!WARNING] 在调试模式下，运行时可能会慢得多。

Installing

要安装 Swift Homomorphic Encryption 目标，请使用 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

Testing

通过以下方式运行单元测试

swift test -c release

要以调试模式运行测试，请运行

swift test

[!WARNING] 在调试模式下，测试将会很慢。

Benchmarking

Swift homomorphic encryption 使用 Benchmark 进行基准测试。 要启用基准测试，请设置环境变量 SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_BENCHMARKING=1。 默认情况下，基准测试需要 jemalloc 依赖项。

[!WARNING] 由于已知的 问题，基准测试可能会间歇性崩溃。 为了可靠执行，可以按照 此处 所述，在不使用 jemalloc 的情况下运行基准测试。

运行基准测试的两种方式如下：

• Xcode
  • 在 Xcode 中打开 swift-homomorphic-encryption 文件夹，并设置 SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_BENCHMARKING=1，例如：
    • open --env SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_BENCHMARKING=1 Package.swift
  • 切换到基准测试目标。
  • 运行该目标，例如通过 Product 菜单。
• 命令行
  • 运行 SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_BENCHMARKING=1 swift package benchmark。
  • 请参阅 Benchmark 文档以获取有关运行基准测试的更多信息。

贡献

如果您有兴趣为 Swift Homomorphic Encryption 做出贡献，请参阅我们的 贡献指南。

文档

Swift Homomorphic Encryption 使用 DocC 进行文档编写。 有关更多信息，请参阅 DocC 文档 和 Swift-DocC 插件。

Xcode

可以通过 Product -> Build Documentation 从 Xcode 构建文档。

命令行

可以通过运行以下命令从命令行构建文档

SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_DOCCPLUGIN=1 swift package generate-documentation

并通过运行以下命令进行预览

SWIFT_HOMOMORPHIC_ENCRYPTION_ENABLE_DOCCPLUGIN=1 swift package --disable-sandbox preview-documentation --target HomomorphicEncryption