加密密钥声明

encryptionKey 声明是一项强大的功能，它允许您的应用程序从用户的钱包中请求一个秘密加密密钥。该密钥是根据钱包的主密钥和您提供的 salt 确定性地派生出来的。它使应用程序能够加密用户特定数据，而无需处理用户的主私钥，从而增强了安全性和隐私性。

工作原理

过程简单而安全：

应用程序发起：
您的应用程序请求一个 encryptionKey 声明，并提供一个唯一的 salt 字符串。
钱包派生密钥：
用户的钱包收到请求。它使用一个安全的密钥派生函数（具体为 SHA3(Buffer.concat(keyPair.sk, salt), 3)）将其主密钥与提供的 salt 结合起来。
用户批准：
钱包会提示用户批准该请求，并解释应用程序想要生成一个加密密钥。
密钥返回：
用户批准后，派生出的密钥将作为 DID Connect 响应的一部分发送回您的应用程序。

这种方法确保了即使两个不同的应用程序使用相同的 salt 请求密钥，派生出的密钥也会不同，因为它们与每个用户唯一的主密钥相关联。

参数

encryptionKey 声明对象接受以下参数：

Parameter	Type	Required	Description
`type`	String	Yes	必须设置为 `'encryptionKey'`。
`description`	String	No	在钱包中向用户显示的消息，用于解释密钥的用途。默认为 'Please provide encryptionKey to continue.'。
`salt`	String	Yes	由您的应用程序提供的唯一字符串。这是密钥派生过程中的关键组成部分。使用不同的 salt 将产生不同的密钥。
`delegation`	String	No	一个可选的 JWT 令牌，用于证明委托关系，允许一个 agent 代表另一个 DID 请求密钥。
`meta`	Any	No	用于存放您想与声明关联的任何自定义元数据的对象。默认为 `{}`。

请求加密密钥

以下是在您的应用程序中请求 encryptionKey 声明的示例。通常，您会在启动 DID Connect 会话时在声明对象中定义它。

DID Connect Claims

const claims = {
  encryptionKey: {
    description: '生成一个密钥来加密您的应用程序设置',
    salt: 'a-unique-and-persistent-salt-for-this-user-and-context',
  },
};

// 这个 claims 对象将被传递给您的 WalletAuthenticator 实例
const { authInfo } = await authenticator.sign({
  claims,
  // ... 其他上下文参数
});

在上面的示例中，应用程序请求一个密钥，为用户提供了一条描述性消息和一个唯一的 salt。

钱包响应

用户批准请求后，您应用程序的回调端点将收到钱包的响应。验证通过后，响应负载中的 claims 数组将包含派生出的加密密钥。

Wallet Response Payload

{
  "userDid": "z1...",
  "userPk": "...",
  "claims": [
    {
      "type": "encryptionKey",
      "salt": "a-unique-and-persistent-salt-for-this-user-and-context",
      "delegation": "",
      "key": "...derived_encryption_key..."
    }
  ],
  "challenge": "...",
  "timestamp": 1678886400
}

您的应用程序随后可以从响应中提取 key，并将其用于加密和解密任务。

使用场景

此声明非常适用于需要保护由您的应用程序存储的用户数据的场景：

加密用户偏好： 在您的数据库中安全地存储用户设置或个人资料信息。
保护应用程序数据： 加密与用户在您应用程序中的会话或活动相关的特定数据。
端到端加密： 建立一个共享密钥，用于创建加密的通信渠道。

通过利用 encryptionKey 声明，您可以构建更安全、更注重隐私保护的应用程序。要深入了解如何处理声明，请继续阅读 WalletAuthenticator API 参考。