如何使用 JWE 格式

本节描述了我们期望如何将 JWE 创建为设备的输入，以便您可以构建自己的工具来从证书和密钥创建 blob。

请参考 SON Web Encryption (JWE) https://datatracker.ietf.org/doc/html/rfc7516 和 SON Web Signature (JWS) https://datatracker.ietf.org/doc/html/rfc7515。

我们使用JSON文档的 序列化 创建JWE blobs。创建JWE blob时需要包含的参数包括：

• JOSE Header （受保护）。在 JSON 对象签名和加密标头中，必须包含以下键值对：

  • "alg"："dir"

    直接算法是我们唯一支持用于加密有效负载的算法，您必须使用设备的初始客户端密码。

  • "enc"："A128GCM" 或"enc"："A256GCM"

    我们支持这两种加密算法。

  • "cisco-action"："add" 或"cisco-action"："popul" 或"cisco-action"："activate" 或"cisco-action"："deactivate"

    这是一个专有密钥，可包含四个值。我们引入此密钥，以便向目标设备表示加密数据的目的。这些值以使用加密数据的设备上的 xAPI 命令命名。

    我们将其命名为 cisco-action ，以减轻与未来JWE扩展的潜在冲突。

  • "cisco-kdf"： { "version"： "1"， "salt"： "base64URLEncodeRandom4+Bytes" }

    另一个专有密钥。我们使用您提供的值作为对设备上密钥派生的输入。版本 必须为 1 （密钥派生功能的版本）。salt 的值必须是至少4字节的base64 URL编码序列，您必须 随机选择。

• WE加密密钥。该字段为空。设备从初始ClientSecret中获取该值。

• WE初始化向量。必须提供 base64url 编码的初始化向量来解密有效负载。IV 必须是随机的 12 字节值（我们使用的是 AES-GCM 密码系列，该系列要求 IV 的长度为 12 字节）。

• JWE AAD （其他经验证的数据）。您必须略过此字段，因为其在紧凑序列化中不受支持。

• WE密文：这是要保密的加密负载。

  载荷可能为空。例如，要重置客户端密码，需要使用空值覆盖。

  根据您试图在设备上执行的操作，有不同类型的有效负载。不同的xAPI命令期望不同的有效载荷，您必须使用cisco操作 键指定有效载荷的用途，如下所示：

  • 使用“cisco-action”：“popul ” 时，密文为新的 Secret。

  • 在""cisco-action"："add" 中，密文是携带证书及其私钥（连接）的PEM blob。

  • 通过""cisco-action"："activate" ，密文是我们激活用于设备标识验证的证书指纹（sha-1的十六进制表示）。

  • 在“"cisco-action"："deactivate" 中，密文是我们要停用用于设备身份验证的证书指纹（sha-1的十六进制表示）。

• JWE 验证标记： 此字段包含验证标记，用于确定整个 JWE 紧凑序列化 blob 的完整性

我们如何从 ClientSecret 中衍生加密密钥

在第一次填充密码后，我们不接受纯文本密码且不输出纯文本密码。这是为了防止能够访问该设备的人进行潜在的字典攻击。

设备软件使用客户端密码作为密钥派生函数 (kdf) 的输入，然后使用派生的密钥在设备上进行内容解密/加密。

这意味着生成 JWE blob 的工具必须遵循相同的过程，以从客户端密码导出相同的加密/解密密钥。

设备使用 scrypt 进行密钥派生（请参阅https://en.wikipedia.org/wiki/Scrypt），所用参数如下：

• CostFactor (N) 为 32768

• BlockSizeFactor (r) 为 8

• ParallelizationFactor (p) 为 1

• Salt是至少4个字节的随机序列；在指定 cisco-kdf 参数时必须提供相同的salt 。

• 密钥长度为 16 字节（如果您选择 AES-GCM 128 算法）或 32 字节（如果您选择 AES-GCM 256 算法）

• 最大内存上限为 64 MB

此参数组是唯一与设备上密钥派生函数兼容的 scrypt 配置。设备上的此kdf称为“version”："1"，这是cisco-kdf 参数当前使用的唯一版本。

工作示例

您可以遵循以下示例，验证您的 JWE 加密过程是否与我们在设备上创建的过程相同。

示例场景是向设备添加 PEM blob（模拟添加证书，使用非常短的字符串而不是完整的证书 + 密钥）。本范例中的客户端密码是ossifrage。

1. 选择加密密码。本范例使用A128GCM （Galois计数器模式中具有128位键的AES）。如果愿意，您的工具可以使用 A256GCM 。

2. 选择 salt（必须为至少 4 字节的随机序列）。本范例使用（十六进制字节）E5 E6 53 08 03 F8 33 F6。Base64url对序列进行编码，以获取 5eZTCAP4M_Y （删除base64填充）。

3. 以下是创建内容加密密钥(cek)的scrypt 调用示例：

   cek=scrypt（password="ossifrage"， salt=4字节序列， N=32768， r=8， p=1， keylength=16）

   派生的密钥应为 16 字节（十六进制），如下所示：95 9e ba 6d d1 22 01 05 78 fe 6a 9d 22 78 ff ac ，base64url编码至 lZ66bdEiAQV4_mqdInj_rA。

4. 选择 12 字节的随机序列用作初始化向量。本范例使用（十六进制） 34 b3 5d dd 5f 53 7b af 2d 92 95 83 ，base64url编码至 NLNd3V9Te68tkpWD。

5. 使用紧凑序列化创建 JOSE 标头（遵循我们在此处使用的参数顺序），然后进行 base64url 编码：

   {"alg"："dir"，"cisco-action"："add"，"cisco-kdf"：{"salt"："5eZTCAP4M_ "，"version"："1"}，"enc"："A128GCM"}

   base64url编码的JOSE标头是eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ9

   这将是 JWE blob 的第一个元素。

6. JWE blob 的第二个元素为空，因为我们没有提供 JWE 加密密钥。

7. JWE blob的第三个元素是初始化向量NLNd3V9Te68tkpWD。

8. 使用 JWE 加密工具生成加密的有效负载和标记。在本例中，未加密的有效负载将是假的PEM blob 是PEM文件

   您应该使用的加密参数为：

   • 负载是 PEM文件

   • 加密密码为 AES 128 GCM

   • base64url 编码的 JOSE 标头作为附加身份验证数据 (AAD)

   Base64url对加密有效负载进行编码，这应会导致f5lLVuWNfKfmzYCo1YJfODhQ

   这是 JWE blob 中的第四个元素（JWE 密文）。

9. Base64url对步骤8中生成的标签进行编码，这应会导致 PE-wDFWGXFFBeo928cfZ1Q

   这是 JWE blob 中的第五个元素。

10. 用点将 JWE blob 的五个元素连接起来 (JOSEheader..IV.Ciphertext.Tag) ，得到：

    JhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6ISwiZW5jIjoiQTEyOEdDTSJ.。9NLNd3V9Te68tkpWD.f5lLVuWNfYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

11. 如果您使用自己的工具派生了与我们在此处显示的相同的 base64url 编码值，则可以使用它们来保护设备的 E2E 加密和已验证身份。

12. 此示例实际上不起作用，但原则上，您的下一步是使用上面创建的 JWE blob 作为添加证书的设备上的 xcommand 的输入：

    x命令安全证书添加 JhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6ISwiZW5jIjoiQTEyOEdDTSJ.。9NLNd3V9Te68tkpWD.f5lLW YCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q