Swift Crypto 是 Apple CryptoKit API 的一个重要部分的开源实现，适用于 Linux 平台。它为跨平台或服务器应用程序带来了 CryptoKit 的优势。

Swift Crypto 以 Swift Package Manager 包的形式提供。要使用它，请在您的 Package.swift 文件中添加以下依赖项

// swift-crypto 1.x and 2.x are almost API compatible, so most clients should
// allow either
.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "3.0.0"),

并在您的目标中，将 Crypto 添加到您的依赖项中。然后您可以 import Crypto 以访问 Swift Crypto 的功能。

Swift Crypto 向任何 Swift 应用程序公开 CryptoKit API 中不依赖于专用硬件的部分。它提供了安全的 API，抽象了现代应用程序中需要使用的许多密码学原语的复杂性。这些 API 鼓励安全地使用底层原语，遵循密码学最佳实践，并且应该是构建需要使用密码学的应用程序的首选。

Swift Crypto 当前的功能涵盖密钥交换、密钥派生、加密和解密、哈希、消息认证等等。

Swift Crypto 在两种不同的模式下编译，具体取决于构建的目标平台。

当为已安装 CryptoKit 的 Apple 平台构建 Swift Crypto 时，Swift Crypto 将其整个 API 表面编译为空，并简单地重新导出 CryptoKit 的 API。这意味着，当使用 Apple 平台时，Swift Crypto 只是将所有工作委托给 CryptoKit 的核心实现，就好像 Swift Crypto 根本不存在一样。

当为在 Linux 上使用而构建 Swift Crypto 时，Swift Crypto 会构建更多的代码。特别是，我们构建了

API 代码和一些直接在 Swift 中实现的密码学原语，对于 Apple CryptoKit 和 Swift Crypto 来说是完全相同的。基于 BoringSSL 的后备实现是 Swift Crypto 独有的。

Swift Crypto 的绝大部分代码旨在与当前版本的 Apple CryptoKit 保持同步。因此，扩展 Swift Crypto API 的补丁将受到谨慎评估。对于任何此类扩展，添加 API 有两种可能的结果。

首先，如果 API 被认为具有普遍价值并适合贡献给 Apple CryptoKit，则该 API 将合并到 Swift Crypto 的 Staging 命名空间中。此 Staging 命名空间是任何预计将在 Apple CryptoKit 中可用但今天不可用的 API 的临时所在地。这使使用者可以在合并后尽快使用该 API。当 API 在 CryptoKit 中普遍可用时，该 API 将在 Staging 命名空间中被弃用，并在主要的 Swift Crypto 命名空间中提供。

其次，如果 API 被认为不符合在通用 CryptoKit 中被接受的标准，但对于服务器用例而言足够重要，则它将被合并到 Server 命名空间中。 API 预计不会离开此命名空间，因为它表明它们不是普遍可用的，只能在使用 Swift Crypto 时访问。

请注意，Swift Crypto 不打算支持所有可能的密码学原语。 Swift Crypto 将专注于安全、现代、广泛有用且不易被误用的密码学原语。这意味着某些密码学算法可能永远不会被支持：例如，由于安全部署 3DES 的难度及其遗留状态，3DES 极不可能被 Swift Crypto 支持。在提议向 Swift Crypto 添加新原语时，请注意该提案可能因此原因而被拒绝。

此存储库中的文件分为两组，一组是名称以 _boring 结尾或位于 BoringSSL 目录中的文件，另一组则不是。

符合上述条件的文件特定于 Swift Crypto 实现。只要它们符合以下标准，就可以相当容易地更改这些文件。如果您的文件需要 import CCryptoBoringSSL 或访问 BoringSSL API，则需要以这种方式标记它。

不带 _boring 后缀的文件是 CryptoKit 公共 API 的一部分。更改这些文件需要更高的门槛，因为对这些文件所做的任何更改都必须伴随 CryptoKit 本身的更改。

在贡献之前，请阅读 CONTRIBUTING.md，还要确保阅读以下两个部分。

此外，只有在新原语实现经过全面测试的情况下，包括使用所有当前可用的测试向量进行测试，才会被接受。如果 Wycheproof 项目为该算法提供了向量，也应该进行测试。必须能够确保我们可以适当地对我们的实现进行回归测试。

如果您有兴趣修复错误，请随时打开 pull request。还请提交带有错误修复的回归测试，以确保它们在将来不会退化。

如果您在使用 CryptoKit 时遇到问题，而不是 Swift Crypto，请使用 Feedback Assistant 来像往常一样提交这些问题。

`gyb`

此项目中的某些文件是使用名为 gyb (“generate your boilerplate”) 的 Swift Utils 工具自动生成（元编程）的。 gyb 包含在 ./scripts/gyb 中。

gyb 将从某些 Foobar.swift.gyb 模板文件生成一些 Foobar.swift Swift 文件。 您不应直接编辑 Foobar.swift，因为下次运行 gyb 时，在该生成文件中的所有手动编辑都将被覆盖。

./scripts/gyb --line-directive "" Sources/Foobar.swift.gyb -o Sources/Foobar.swift

更方便的是，您可以运行 bash 脚本 ./scripts/generate_boilerplate_files_with_gyb.sh 以从其对应的 gyb 模板生成所有 Swift 文件。

如果您添加新的 .gyb 文件，则应在其内部附加 // MARK: - Generated file, do NOT edit 警告，例如

// MARK: - Generated file, do NOT edit
// any edits of this file WILL be overwritten and thus discarded
// see section `gyb` in `README` for details.

最新版本的 Swift Crypto 支持 Swift 5.5 及更高版本。 Swift Crypto 版本支持的最低 Swift 版本在下面详细说明

Swift Crypto	最低 Swift 版本
`2.0.0 ..< 2.1.0`	5.2
`2.1.0 ..< 2.2.0`	5.4
`2.2.0 ...`	5.5

Swift Crypto 遵循 SemVer 2.0.0。我们的公共 API 与 CryptoKit 的 API 相同（除非我们完全缺少实现），以及 Server 和 Staging 命名空间中的所有内容。任何以下划线开头的符号以及任何以下划线开头的产品都不受语义版本控制的约束：这些 API 可能会在没有警告的情况下更改。我们不维护稳定的 ABI，因为 Swift Crypto 是仅源代码分发。

这对您意味着，您应该使用版本范围依赖于 Swift Crypto，该范围涵盖从您需要的最低 Swift Crypto 版本到下一个主要版本之间的所有版本。在 SwiftPM 中，可以很容易地指定例如 from: "1.0.0"，这意味着您支持从 1.0.0 到（不包括）2.0.0 的每个版本的 Swift Crypto。 SemVer 和 Swift Crypto 的公共 API 保证应该会产生一个可以正常运行的程序，而无需担心测试每个版本的兼容性。

Swift Crypto 2.0.0 于 2021 年 9 月发布。 Swift Crypto 2.0.0 和 1.0.0 之间唯一的重大更改是在 CryptoKitError 枚举中添加了新 case。因此，对于大多数用户来说，依赖 1.0.0 或 2.0.0 系列版本是安全的。

.package(url: "https://github.com/apple/swift-crypto.git", "1.0.0" ..< "3.0.0"),

Swift Crypto 通常在 macOS 上会延迟到操作系统的 CryptoKit 实现。自然，这使得在 macOS 上开发 Swift Crypto 变得棘手。要使 Swift Crypto 在 macOS 上构建开源实现，请在 Package.swift 中，取消注释读取 //.define("CRYPTO_IN_SWIFTPM_FORCE_BUILD_API") 的行，因为这将强制 Swift Crypto 构建其公共 API。

Swift Crypto

使用 Swift Crypto

功能

实现

演进

代码组织

贡献

贡献新的原语

贡献错误修复

开始贡献

`gyb`

安全性

Swift 版本

兼容性

在 macOS 上开发 Swift Crypto