Virgil Core SDK Objective-C/Swift
简介 | SDK 功能 | 安装 | 配置 SDK | 使用实例 | 文档 | 支持
简介
Virgil Core SDK 是一个低级库，它使开发者能够快速使用 Virgil Cards Service API，并将端到端安全添加到他们新的或现有的数字解决方案中。
如果您需要针对多设备支持、群聊等更多的安全功能，请尝试我们的高级 Virgil E3Kit 框架。
SDK 功能
- 与Virgil Cards Service进行通信
- 管理用户的公钥
- 加密、签名、解密和验证数据
- 将私钥存储在安全本地存储中
- 使用Virgil Crypto Library
安装
Virgil Core SDK作为一组框架提供。这些框架通过Carthage和CocoaPods进行分发。在本指南中，您还将找到另一个包——用于执行加密操作的Virgil Crypto Library。
所有框架都支持以下系统
- iOS 11.0+
- macOS 10.11+
- tvOS 11.0+
- watchOS 4.0+
COCOAPODS
CocoaPods是Cocoa项目的依赖管理器。您可以使用以下命令安装它
$ gem install cocoapods要使用CocoaPods将VirgilSDK集成到Xcode项目中，请在您的Podfile中指定它
target '<Your Target Name>' do
use_frameworks!
pod 'VirgilSDK', '~> 8.0'
end然后，运行以下命令
$ pod installCarthage
Carthage是一个去中心化的依赖管理器，用于构建您的依赖关系并提供二进制框架。
您可以使用以下命令使用Homebrew安装Carthage
$ brew update
$ brew install carthage要使用Carthage将VirgilSDK集成到您的Xcode项目中，请在本项目的根目录中创建一个名为Cartfile的空文件，并在其中添加以下行
github "VirgilSecurity/virgil-sdk-x" ~> 8.0
链接到预构建的二进制文件
要将预构建的框架链接到您的应用程序中，请运行以下命令
$ carthage update --use-xcframeworks --no-use-binaries这将为每个依赖项构建或从github Releases中下载预编译的框架。
为 iOS/tvOS/watchOS 构建项目
在您的应用程序目标的“通用”设置选项卡中，在“链接的框架和库”部分，从您的项目文件夹内的“Carthage/Build”文件夹中添加以下框架
- VirgilSDK
- VirgilCrypto
- VirgilCryptoFoundation
- VSCCommon
- VSCFoundation
为每个框架检查嵌入和签名。
为 macOS 构建项目
在您的应用程序目标的“通用”设置选项卡中，在“嵌入式二进制文件”部分，从磁盘上的 Carthage/Build 文件夹拖放以下框架
- VirgilSDK
- VirgilCrypto
- VirgilCryptoFoundation
- VSCCommon
- VSCFoundation
此外，您还需要在 macOS 上复制调试符号以进行调试和崩溃报告。
在您的应用程序目标的“构建阶段”设置选项卡中，单击“+”图标并选择“新建复制文件阶段”。单击“目标”下拉菜单并选择“产品目录”。对于每个框架，拖放对应的 dSYM 文件。
Swift 包管理器
Swift 包管理器是苹果官方用于管理 Swift 代码分发的工具。
苹果的文档可用于将框架添加到 Xcode 项目中。
配置 SDK
本部分包含有关如何设置 Virgil Core SDK 模块以进行用户认证、管理 Virgil 卡和存储私钥的指南。
设置认证
使用基于 JSON Web Token 标准（JWT）以及一些 Virgil 修改的令牌设置用户认证。
为了调用Virgil服务（例如，在Virgil Cards服务中发布用户的卡片），您需要有一个包含用户身份的JSON Web Token（"JWT"），这是一个唯一的字符串，用于在您的应用程序中识别每个用户。
您需要凭证
| 参数 | 说明 |
|---|---|
| App ID | 您的应用程序在Virgil仪表板上的ID |
| App Key ID | 一个唯一字符串值，用于在Virgil开发门户网站上识别您的账户 |
| App Key | 用于对调用Virgil服务的API进行签名的私钥。出于安全考虑，您仅在使用时显示App Key。请不要忘记将其保存在安全位置以供下个步骤使用 |
在客户端设置JWT提供程序
使用以下代码行来指定您的项目中要使用的JWT生成源
import VirgilSDK
// Get generated token from server-side
let authenticatedQueryToServerSide: ((String) -> Void) -> Void = { completion in
completion("eyJraWQiOiI3MGI0NDdlMzIxZj....MK7p7Ak")
}
// Setup AccessTokenProvider
let accessTokenProvider = CallbackJwtProvider { tokenContext, completion in
authenticatedQueryToServerSide { jwtString in
completion(jwtString, nil)
}
}在服务器端生成JWT
对于本部分，我们已经创建了一个示例后端，以展示如何设置您的后端以生成JWT。要设置和运行示例后端，请转到您选择的GitHub仓库
Node.js | Golang | PHP | Java | Python，并按照README中的说明进行操作。
设置卡片验证器
Virgil Card Verifier可以帮助您自动验证用户卡片的签名，例如，从Virgil Cards服务获取卡片时。
默认情况下，VirgilCardVerifier仅验证两个签名-卡主和Virgil Cards Service的签名。
使用以下代码行设置VirgilCardVerifier
import VirgilSDK
import VirgilCrypto
// initialize Crypto library
let cardCrypto = VirgilCardCrypto()
let yourBackendVerifierCredentials =
VerifierCredentials(signer: "YOUR_BACKEND",
publicKey: Data(base64Encoded: publicKeyStr)!)
let yourBackendWhitelist =
try! Whitelist(verifiersCredentials: [yourBackendVerifierCredentials])
let cardVerifier = VirgilCardVerifier(cardCrypto: cardCrypto,
whitelists: [yourBackendWhitelist])
设置卡管理器
本小节展示了如何设置卡管理器模块，以帮助您管理用户的公钥。
使用卡管理器：
- 指定一个访问令牌（JWT）提供者。
- 指定一个用于验证您的用户、应用程序服务器、Virgil服务的签名验证器（可选）。
使用以下代码行设置卡管理器：
// initialize cardManager and specify accessTokenProvider, cardVerifier
let cardManagerParams = CardManagerParams(cardCrypto: cardCrypto,
accessTokenProvider: accessTokenProvider,
cardVerifier: cardVerifier)
let cardManager = CardManager(params: cardManagerParams)用法示例
在练习用法示例之前，请确保已配置SDK。有关更多信息，请参阅配置SDK部分。
在卡片服务生成并发布Virgil卡片
使用以下代码行创建带有公钥的用户卡并将其发布到Virgil卡片服务：
import VirgilSDK
import VirgilCrypto
// save a private key into key storage
let data = try! crypto.exportPrivateKey(keyPair.privateKey)
let entry = try! keychainStorage.store(data: data, withName: "Alice", meta: nil)
// publish user's card on the Cards Service
cardManager.publishCard(privateKey: keyPair.privateKey, publicKey: keyPair.publicKey).start { result in
switch result {
// Card is created
case .success(let card): break
// Error occured
case .failure(let error): break
}
}先签名后加密数据
Virgil Core SDK允许您使用用户的私钥和Virgil卡片来签名和加密任何类型的数据。
以下示例中，我们从自定义密钥存储中加载私钥，并从Virgil卡片服务获取接收者的卡片。接收者卡片包含一个公钥，我们将使用它来加密数据和验证签名。
import VirgilSDK
import VirgilCrypto
// prepare a message
let messageToEncrypt = "Hello, Bob!"
let dataToEncrypt = messageToEncrypt.data(using: .utf8)!
// prepare a user's private key
let alicePrivateKeyEntry = try! keychainStorage.retrieveEntry(withName: "Alice")
let alicePrivateKey = try! crypto.importPrivateKey(from: alicePrivateKeyEntry.data)
// using cardManager search for user's cards on Cards Service
cardManager.searchCards(identities: ["Bob"]).start { result in
switch result {
// Cards are obtained
case .success(let cards):
let bobRelevantCardsPublicKeys = cards
.map { $0.publicKey }
// sign a message with a private key then encrypt on a public key
let encryptedData = try! crypto.signAndEncrypt(dataToEncrypt,
with: alicePrivateKey,
for: bobRelevantCardsPublicKeys)
// Error occured
case .failure(let error): break
}
}解密数据和验证签名
一旦用户收到已签名和加密的消息，他们可以用自己的私钥对其进行解密，并使用发送者的Card验证签名。
import VirgilSDK
import VirgilCrypto
// prepare a user's private key
let bobPrivateKeyEntry = try! keychainStorage.retrieveEntry(withName: "Bob")
let bobPrivateKey = try! exporter.importPrivateKey(from: bobPrivateKeyEntry.data)
// using cardManager search for user's cards on Cards Service
cardManager.searchCards(identities: ["Alice"]).start { result in
switch result {
// Cards are obtained
case .success(let cards):
let aliceRelevantCardsPublicKeys = cards.map { $0.publicKey }
// decrypt with a private key and verify using a public key
let decryptedData = try! crypto.decryptAndVerify(encryptedData,
with: bobPrivateKey,
usingOneOf: aliceRelevantCardsPublicKeys)
// Error occured
case .failure(let error): break
}
}通过ID获取卡
使用以下代码行，通过ID从Virgil Cloud获取用户卡。
import VirgilSDK
// using cardManager get a user's card from the Cards Service
cardManager.getCard(withId: "f4bf9f7fcbedaba0392f108c59d8f4a38b3838efb64877380171b54475c2ade8").start { result in
switch result {
// Card is obtained
case .success(let card): break
// Error occurred
case .failure(let error): break
}
}通过用户身份获取卡
对于单个用户，可以使用以下代码行通过用户的身份获取用户的Card。
import VirgilSDK
// using cardManager search for user's cards on Cards Service
cardManager.searchCards(identity: "Bob").start { result in
switch result {
// Cards are obtained
case .success(let cards): break
// Error occurred
case .failure(let error): break
}
}撤销卡
如果用户不再需要卡片，您可以撤销用户的Card。已撤销的卡仍可通过其标识符获得，但在搜索查询中不会出现。
import VirgilSDK
let result = cardManager.revokeCard(withId: card.identifier).start { result in
switch result {
// Card is revoked
case .success: break
// Error occured
case .failure(let error): break
}
}使用VirgilCrypto生成密钥对
您可以使用以下代码生成密钥对并将其保存到安全键存储中。
import VirgilCrypto
let crypto = try! VirgilCrypto()
let keyPair = try! crypto.generateKeyPair()使用密钥链存储保存和检索密钥
import VirgilSDK
import VirgilCrypto
let storageParams = try! KeychainStorageParams.makeKeychainStorageParams()
let keychainStorage = KeychainStorage(storageParams: storageParams)
// export key to Data
let data = try! crypto.exportPrivateKey(keyPair.privateKey)
let identity = "Alice"
// save key data
let entry = try! keychainStorage.store(data: data, withName: identity, meta: nil)
// retrieve key data
let retrievedEntry = try! keychainStorage.retrieveEntry(withName: identity)
// import key from Data
let privateKey = try! exporter.importPrivateKey(from: retrievedEntry.data)文档
Virgil Security 提供了一组强大的 API，您可以访问开发者文档来开始您的使用。
许可证
本库根据3-clause BSD 许可证发布。
支持
我们的开发者支持团队在这里为您提供帮助。了解更多信息，请访问我们的帮助中心。
您可以在Twitter上找到我们，或给我们发送电子邮件 [email protected]。
此外，您还可以在我们的Slack社区从我们的支持团队获得额外的帮助。