EosioSwiftVault 1.0.0

EosioSwiftVault 1.0.0

×

由Paul Kim、Mark Johnson、Brandon Fancher维护。

EosioSwiftVault 1.0.0

  • 由
  • Todd Bowden、Serguei Vinnitskii、Farid Rahmani、Brandon Fancher、Mark Johnson、Paul Kim、Steve McCoole 和 Ben Martell。

Swift Logo

EOSIO SDK for Swift: Vault

Software License Swift 5.0

EOSIO SDK for Swift: Vault包括两个主要组件；Vault 和 Vault Signature Provider。

Vault是一个工具库，用于处理公钥/私钥并使用Apple的钥匙串和Secure Enclave进行签名。它公开了可以直接调用的密钥生成、管理和签名功能。

Vault Signature Provider是EOSIO SDK for Swift的插件签名提供者，它依赖于Vault。它允许使用存放在钥匙串或设备Secure Enclave中的密钥进行交易签名。

所有产品和公司名称均为其各自持有者的商标™或注册®商标。使用它们并不意味着与它们有联系或得到它们的认可。

内容

关于签名提供者

签名提供者抽象可以说是EOSIO SDK for Swift提供者中最有用的。它负责

  • 找到可用于签名的密钥（getAvailableKeys），以及
  • 请求和获取可用密钥子集的交易签名（signTransaction）。

通过简单切换交易上的签名提供者，签名请求可以以任何数量方式进行路由。需要平台密钥链或安全元素的签名吗？使用以下签名提供者配置EosioTransaction。需要软件签名吗？请查看Softkey Signature Provider组件，这是EOSIO SDK for Swift的一部分。

所有签名提供者都必须符合EosioSignatureProviderProtocol 协议。

先决条件

  • Xcode 11 或更高版本
  • CocoaPods 1.9.3 或更高版本
  • Swift Package Manager 5.2 或更高版本
  • 对于 iOS，iOS 12.0+

Swift 包管理器安装

如果使用 Vault 作为 Vault 签名提供者的一部分，则 Vault 将作为依赖项自动安装。

如果您希望使用 Vault 签名提供者，请向您的应用程序依赖项添加从 https://github.com/EOSIO/eosio-swift-vault 的 EosioSwiftVaultSignatureProvider 产品。

或者要将其包含在库中，请将以下内容添加到您的 Package.swift 定义中

// swift-tools-version:5.2
// The swift-tools-version declares the minimum version of Swift required to build this package.

import PackageDescription

let package = Package(
    name: "MyName",
    platforms: [
        .iOS(.v12)
    ],
    products: [
        // Products define the executables and libraries produced by a package, and make them visible to other packages.
        .library(
            name: "MyLibrary",
            targets: ["MyLibrary"]),
    ],
    dependencies: [
        // Dependencies declare other packages that this package depends on.
        // .package(url: /* package url */, from: "1.0.0"),
        .package(name: "EosioSwiftVault", url: "https://github.com/EOSIO/eosio-swift-vault", from: "1.0.0"))
    ],
    targets: [
        // Targets are the basic building blocks of a package. A target can define a module or a test suite.
        // Targets can depend on other targets in this package, and on products in packages which this package depends on.
        .target(
            name: "MyLibrary",
            dependencies: [
                .product(name: "EosioSwiftVaultSignatureProvider", package: "EosioSwiftVault")
        ]),
        .testTarget(
            name: "MyLibraryTests",
            dependencies: ["MyLibrary"]),
    ]
)

如果您只想要 Vault 组件，您可以在依赖项中的产品名称定义中将 EosioSwiftVault 替换为 EosioSwiftVaultSignatureProvider。

CocoaPods 安装

Vault 和 Vault 签名提供者在 Cocoapods 中被划分为子模块。如果您从 EOSIO SDK for Swift：Vault 安装整个 pod，您将获得 Vault 签名提供者和 Vault。Vault 将作为依赖项自动安装。为此，请将以下内容添加到您的 Podfile

use_frameworks!

target "Your Target" do
  pod "EosioSwiftVault", "~> 1.0.0"
end

然后运行 pod install。

如果您直接使用 Vault，请在您的 Podfile 中添加以下 pods

use_frameworks!

target "Your Target" do
  pod "EosioSwiftVault/Vault", "~> 1.0.0"
end

然后运行 pod install。

附加安装步骤

如果在您的包管理器集成后，正在使用 Vault 签名提供者组件，则需要遵循一些额外的步骤。

您还必须将您的应用程序配置为应用组的成员。有关在 Xcode 中启用和配置应用组功能的说明，请参阅苹果的此处文档。

现在，Vault 签名提供者根据EOSIO SDK for Swift 基本使用说明，已准备好在 EOSIO SDK for Swift 中使用。

Vault签名提供者使用说明

通常，在签名过程中，签名提供者由EosioTransaction调用。（请在此处查看示例。）但是，如果您需要获取可用的密钥或直接请求签名，可以通过以下方式调用此库

let signProvider = try? EosioVaultSignatureProvider(accessGroup: "YOUR_ACCESS_GROUP")
let publicKeysArray = signProvider?.getAvailableKeys() // Returns the public keys.

在此处了解有关访问组的更多信息。

要签名EosioTransaction，请创建一个EosioTransactionSignatureRequest对象，并使用请求调用EosioVaultSignatureProvider.signTransaction(request:completion:)方法

var signRequest = EosioTransactionSignatureRequest()
signRequest.serializedTransaction = serializedTransaction
signRequest.publicKeys = publicKeys
signRequest.chainId = chainId

signProvider.signTransaction(request: signRequest) { (response) in
    ...
}

Vault签名提供者库方法

此库实现了EosioSignatureProviderProtocol。它实现了以下协议方法

  • EosioVaultSignatureProvider.signTransaction(request:completion:) 签名 EosioTransaction。
  • EosioVaultSignatureProvider.getAvailableKeys(...) 返回一个包含与对象初始化时使用的私钥相关联的公钥的数组。

要初始化实现

  • EosioVaultSignatureProvider.init(accessGroup:requireBio:) 初始化签名提供者。
    • accessGroup：在此处了解有关访问组的更多信息。
    • requireBio：默认为false。某些密钥可能需要生物识别身份验证，而不管此标志如何设置。对于那些不需要生物识别身份验证的密钥，此标志可以强制进行生物检查。

您可以通过直接在随 Vault 签名提供者一起提供的 Vault 组件上调用方法来访问其他 Keychain 和/或 Secure Enclave 功能。

功能库使用

如果您愿意，可以直接操作功能库，而不是通过功能签名提供程序。下面几节描述了功能库的主要组件以及如何与它们交互。

Eosio功能库

与EOSIO Swift SDK交互的主要类是：EosioVault。使用accessGroup实例化一个EosioVault对象如下

import EosioSwiftVault

let vault = EosioVault(accessGroup: accessGroup)

accessGroup是一个App Group Identifier或Keychain Access Group Identifier，它允许在相同开发者账户内的不同应用程序和应用程序扩展之间共享密钥。

密钥生成

功能库公开了用于生成新EOSIO密钥的函数。新密钥可以生成并存储在设备的Secure Enclave或Keychain中。注意：如果密钥存储在Secure Enclave中，则无法直接访问或导出私钥。

重要：当前密钥元数据必须遵守JSONSerialization的转换规则。不这样做会导致应用程序错误。

要在Secure Enclave中创建密钥

let newKey = try vault.newVaultKey(secureEnclave: true, protection: .whenUnlockedThisDeviceOnly, bioFactor: .none, metadata: [String: Any])

或使用便利函数

let newKey = try vault.newSecureEnclaveKey(bioFactor: .none, metadata: [String: Any])

在Keychain中创建密钥

let newKey = try vault.newVaultKey(secureEnclave: false, protection: .whenUnlockedThisDeviceOnly, bioFactor: .none, metadata: [String: Any])

bioFactor是Keychain在用此密钥签名消息时所需生物识别安全类型的密钥。可以关联到此密钥的任何数据是metadata。使用密钥的访问权限为protection。

上述每个函数都将返回一个EosioVault.VaultKey。要访问EOSIO公钥和私钥

let publicKey = newKey.eosioPublicKey
let privateKey = newKey.eosioPrivateKey

对于Secure Enclave密钥，eosioPrivateKey是nil，因为它无法访问。

签名

在大多数情况下，签名通过功能签名提供程序组件处理。但是，也可以直接使用EosioVault的实例对消息进行签名

let signature = vault.sign(message: message, eosioPublicKey: publicKey, requireBio: true) { (signature, error) in
	// handle signature or error
}

生物识别需求可以作为密钥的一部分设置，本身设置，或作为独立的软件检查来实施。《requireBio》标志将要求使用生物识别识别来使用此密钥进行签名，即使密钥不需要也是如此。然而，将《requireBio》设置为《false》 不会 在键需要时禁用生物识别识别。

密钥管理

Vault库公开了获取现有密钥、添加外部密钥、删除密钥以及修改现有密钥的元数据的函数。

获取EOSIO公钥的单个VaultKey

let key = try getVaultKey(eosioPublicKey: publicKey)

获取所有密钥的数组

let keys = try getAllVaultKeys()

将外部密钥（带私有密钥）添加到密钥链

try vault.addExternal(eosioPrivateKey: privateKey, metadata: [String: Any])

删除一个密钥

try deleteKey(eosioPublicKey: publicKey)

更新现有密钥，更新元数据属性然后

update(key: myKey)

文档

请参阅在https://eosio.github.io/eosio-swift-vault生成的代码文档或在克隆此存储库。可以通过浏览器打开docs/EosioSwiftVault/index.html文件来引用Vault文档。可以在docs/EosioSwiftVaultSignatureProvider/index.html找到Vault签名提供者文档。可以通过在存储库中运行update_documentation.sh脚本来重新生成或更新文档。

想要帮忙吗？

有兴趣贡献吗？太好了！这里有一些贡献指南和行为准则。

许可证

MIT

重要

请参阅LICENSE了解版权和许可条款。Block.one作为EOSIO社区的一员，自愿做出贡献，不负责确保软件及其相关应用的总体性能。我们对于软件或相关文档，无论明示或暗示，不做任何表示、保证、担保或承诺，包括但不限于适用性、特定用途的适用性和非侵权性。在任何情况下，我们均不对任何因软件或文档或其使用或与软件或文档的其他往来而产生的索赔、损害或其他责任承担任何责任，无论是否由于合同或侵权或其他原因。任何测试结果或性能数据仅供参考，并不能反映所有条件下的性能。关于任何第三方或第三方产品、服务或其他资源的引用，不代表Block.one的认可或推荐。我们不对您使用或依赖任何这些资源承担责任，并放弃所有责任与义务。第三方资源可能随时更新、更改或终止，所以此处信息可能已过时或不准确。任何使用或向第三方提供 软件、商品或服务的人士，应告知这些第三方关于许可条款、免责声明和责任限制。

钱包及其相关组件是复杂的软件，需要最高级别的安全。如果构建或使用不当，可能会危害用户的私钥和数字资产。在使用前，钱包应用及其相关组件应进行彻底的安全评估。只有经验丰富的开发者才能使用此软件。