跳到主要内容

密钥对声明

密钥对声明是一项强大的功能，允许你的应用程序请求用户的钱包生成一个新的加密密钥对。这对于创建新的、特定于应用程序的账户或身份特别有用，这些账户或身份由用户的钱包安全管理，但专用于与你的服务进行交互。

你可以将管理用户凭证的责任转移到用户的 DID 钱包，而不是在你的服务器上管理，从而增强安全性和用户控制。

使用场景

  • 特定于应用的账户： 当用户注册时，你可以请求一个新的密钥对，在你的应用程序中为他们创建一个专用账户。这个新账户的 DID 与用户的主 DID 是不同的。
  • 会话或设备密钥： 为特定会话或设备生成临时密钥对，通过限制密钥的范围和生命周期来增强安全性。
  • 身份迁移： 通过指定 migrateFrom 属性，方便用户从旧账户迁移到新账户。

工作原理

当你请求一个 keyPair 声明时，DID 钱包会向用户显示你提供的描述信息。如果用户批准，钱包将根据你设置的参数（targetType）生成一个新的密钥对。默认情况下，钱包还会在区块链上声明这个新的 DID。然后，钱包通过安全的 DID Connect 通道将新的密钥对（公钥、私钥和地址）返回给你的应用程序。

参数

keyPair 声明接受以下参数：

名称类型描述
descriptionstring必需。 向用户显示一条消息，解释为什么需要新的密钥对。
monikerstring必需。 新账户的人类可读名称，将显示在用户的钱包中。必须匹配正则表达式 ^[a-zA-Z0-9][-a-zA-Z0-9_]{2,128}$。
declareboolean可选。如果为 true（默认值），新的 DID 将在链上声明。设置为 false 以生成链下密钥对。
migrateFromstring可选。要从中迁移的 DID 地址。钱包可以使用此地址将新账户链接到旧账户。
targetTypeobject可选。一个指定待生成密钥对的加密属性的对象。

targetType 对象

你可以使用 targetType 对象自定义生成的密钥对类型：

键类型默认值描述
rolestringaccountDID 的角色，例如 account、application、blocklet。
keystringed25519加密密钥算法，例如 ed25519、secp256k1。
hashstringsha3用于生成地址的哈希算法，例如 sha3、sha2、keccak。
encodingstringbase58地址的编码方式，例如 base58、base16。

示例：请求新账户

以下是如何为用户请求新密钥对的示例，该密钥对可用作其在你的应用程序中的账户。

Requesting a new key pair

javascript
const claims = {
  keyPair: {
    description: '为我们的出色应用创建一个新账户',
    moniker: 'my-app-account',
    targetType: {
      role: 'account',
    },
  },
};

// 在你的处理程序中
const { authInfo } = await authenticator.sign({
  claims,
  // ... 其他上下文属性
});

示例：为 Blocklet 生成密钥对

如果你正在构建一个 Blocklet，你可能需要一个具有特定角色的密钥对。你也可以选择不立即在链上声明它，并从现有的 DID 迁移。

Requesting a key pair for a blocklet

javascript
const claims = {
  keyPair: {
    description: '生成一个密钥对来管理你的新 Blocklet',
    moniker: 'my-blocklet-key',
    declare: false, // 生成密钥对，但不广播声明交易
    migrateFrom: 'z3CtKiQt2QnLXaZfEfBYvJHTZoPXJggnHEYx4', // 要从中迁移的 DID
    targetType: {
      role: 'blocklet',
      key: 'ed25519',
      hash: 'sha3',
    },
  },
};

// 在你的处理程序中
const { authInfo } = await authenticator.sign({
  claims,
  // ... 其他上下文属性
});

钱包响应

如果用户批准请求，你的应用程序的 onAuth 回调函数将在 claims 数组中收到新生成的密钥对。单个 keyPair 声明的响应如下所示：

Wallet Response Example

json
{
  "type": "keyPair",
  "sk": "...", // 新密钥对的私钥
  "pk": "...", // 新密钥对的公钥
  "address": "...", // 新密钥对的 DID 地址
  "moniker": "my-app-account",
  "meta": {}
}

你的应用程序应安全地处理收到的私钥（sk），因为它授予了对新创建的 DID 的完全控制权。

现在你已经了解了如何请求新的密钥对，你可能对为其他目的派生密钥感兴趣。

下一步：加密密钥声明

了解如何请求钱包使用提供的盐值从其主密钥派生一个秘密加密密钥。

阅读更多