CryptoLib Swift

这个库包含了 Cryptomator for iOS 使用的所有加密函数。该项目的目的是提供一个独立的轻量级库，它具有自己的发布周期，也可以在其他项目中使用。

有关 Cryptomator 加密方案的更多信息，请访问 docs.cryptomator.org 上的安全架构页面。

要求

iOS 13.0 或更高版本
macOS 10.15 或更高版本

安装

Swift 包管理器

.package(url: "https://github.com/cryptomator/cryptolib-swift.git", .upToNextMinor(from: "1.1.0"))

用法

主密钥 (Masterkey)

Masterkey 是一个类，仅包含用于 AES 加密/解密和 MAC 身份验证的密钥材料。

工厂 (Factory)

这将使用安全的随机字节创建一个新的主密钥。

let masterkey = try Masterkey.createNew()

另一种方法是从原始字节创建主密钥。

let aesMasterKey = ...
let macMasterKey = ...
let masterkey = Masterkey.createFromRaw(aesMasterKey: aesMasterKey, macMasterKey: macMasterKey)

主密钥文件 (MasterkeyFile)

MasterkeyFile 是主密钥文件的表示。使用它可以解锁主密钥文件（并获得一个 Masterkey）、锁定主密钥文件（并将其序列化为 JSON）或更改密码。

工厂 (Factory)

使用 URL 提供的内容创建主密钥文件

let url = ...
let masterkeyFile = try MasterkeyFile.withContentFromURL(url: url)

或从 JSON 数据创建

let data = ...
let masterkeyFile = try MasterkeyFile.withContentFromData(data: data)

解锁 (Unlock)

拥有主密钥文件后，您可以尝试解锁。如果成功，它会将存储的加密和 MAC 密钥解包到主密钥中，该主密钥可用于加密器 (cryptor)。

let masterkeyFile = ...
let passphrase = ...
let pepper = ... // optional
let masterkey = try masterkeyFile.unlock(passphrase: passphrase, pepper: pepper)

解锁过程也可以分两步进行

let masterkeyFile = ...
let passphrase = ...
let pepper = ... // optional
let kek = try masterkeyFile.deriveKey(passphrase: passphrase, pepper: pepper)
let masterkey = try masterkeyFile.unlock(kek: kek)

如果您想在额外的步骤中派生密钥，这将很有用，因为该函数是内存密集型的（使用 scrypt）。然后，可以将结果用于其他地方，例如，在内存受限的进程中。

锁定 (Lock)

为了持久化主密钥，请使用此方法将其加密/包装的主密钥和其他元数据导出为 JSON 数据。

let masterkey = ...
let vaultVersion = ...
let passphrase = ...
let pepper = ... // optional
let scryptCostParam = ... // optional
let data = try MasterkeyFile.lock(masterkey: masterkey, vaultVersion: vaultVersion, passphrase: passphrase, pepper: pepper, scryptCostParam: scryptCostParam)

更改密码 (Change Passphrase)

可以使用新密码重新加密主密钥。

let masterkeyFileData = ...
let oldPassphrase = ...
let newPassphrase = ...
let pepper = ... // optional
let scryptCostParam = ... // optional
try MasterkeyFile.changePassphrase(masterkeyFileData: masterkeyFileData, oldPassphrase: oldPassphrase, newPassphrase: newPassphrase, pepper: pepper, scryptCostParam: scryptCostParam)

加密器 (Cryptor)

Cryptor 是用于 Cryptomator 存储卷 (vaults) 的加密操作的核心类。

构造函数 (Constructor)

通过提供主密钥和方案（例如，.sivGcm）来创建加密器。

let masterkey = ...
let scheme = ...
let cryptor = Cryptor(masterkey: masterkey, scheme: scheme)

确保您正在处理的数据与提供的方案兼容。

路径加密和解密 (Path Encryption and Decryption)

加密目录 ID，以便确定加密的目录 URL。

let cryptor = ...
let dirId = ...
let encryptedDirId = try cryptor.encryptDirId(dirId)

通过提供目录 ID 来加密和解密文件名。

let cryptor = ...
let filename = ...
let dirId = ...
let ciphertextName = try cryptor.encryptFileName(filename, dirId: dirId)
let cleartextName = try cryptor.decryptFileName(ciphertextName, dirId: dirId)

文件内容加密和解密 (File Content Encryption and Decryption)

通过 URL 加密和解密文件内容。这些方法支持隐式进度组合。

let cryptor = ...
let fileURL = ...
let ciphertextURL = ...
let cleartextURL = ...
try cryptor.encryptContent(from: fileURL, to: ciphertextURL)
try cryptor.decryptContent(from: ciphertextURL, to: cleartextURL)

文件大小计算 (File Size Calculation)

以 O(1) 确定明文和密文大小。

let cryptor = ...
let size = ...
let ciphertextSize = cryptor.calculateCiphertextSize(size)
let cleartextSize = try cryptor.calculateCleartextSize(ciphertextSize)

贡献 (Contributing)

如果您想报告错误、提出问题或帮助我们进行编码，请阅读我们的贡献指南。

一般来说，以下首选项用于选择加密原语的实现：

Apple CryptoKit (AES-GCM)
Apple Swift Crypto (HMAC)
Apple CommonCrypto (AES-CTR, RFC 3394 密钥派生)

此项目使用 SwiftFormat 和 SwiftLint 来强制执行代码风格和约定。如果您尚未安装这些工具，请安装它们。

请确保您的代码格式正确并且通过了 linter 验证。最简单的方法是设置一个 pre-commit hook。在 .git/hooks/pre-commit 创建一个文件，内容如下：

./Scripts/process.sh --staged
exit $?

并使您的 pre-commit hook 可执行

chmod +x .git/hooks/pre-commit

行为准则 (Code of Conduct)

帮助我们保持 Cryptomator 的开放性和包容性。请阅读并遵守我们的行为准则。

许可 (License)

该项目在 AGPLv3 下对 FOSS 项目进行双重许可，并为独立软件供应商和经销商提供源自 LGPL 的商业许可。如果您想在未根据 AGPL 许可的应用程序中使用此库，请随时联系我们的销售团队。