我们如何使用JWE格式

本节介绍我们期望如何创建JWE作为设备的输入，以便您可以构建自己的工具，从证书和密钥中创建blobs。

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

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

• JOSE标题 （受保护）。在JSON对象签名与加密标题中，您必须包括以下密钥值对：

  • "alg":"dir"

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

  • "enc":"A128GCM" 或 "enc":"A256GCM"

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

  • "cisco-action": "add" 或 "cisco-action": "populate""cisco-action": "activate""cisco-action": "deactivate"

    这是专有密钥和可以使用的四个值。我们引入此密钥，以向目标设备发出加密数据的目的。这些值以使用加密数据的设备上的xAPI命令命名。

    我们命名它cisco-action 是为了缓解与未来JWE扩展名的潜在冲突。

  • "cisco-kdf": { "version": "1", "salt": "base64URLEncodedRandom4+Bytes" }

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

• JWE加密密钥。此字段为空。设备从最初的ClientSecret中获取它。

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

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

• JWE密码：这是您希望保密的加密有效负载。

  有效负载可能为空。例如，要重置客户端秘密，您需要用空值覆盖它。

  有不同类型的有效负载，具体取决于您尝试在设备上做什么。不同的xAPI命令期望不同的有效负载，您必须使用 cisco-action 键指定有效负载的目的，如下所示：

  • "cisco-action":"populate" 密码文本为新的ClientSecret。

  • 使用“"cisco-action":"add" 密码文本是携带证书及其私钥（连接）的PEM blob。

  • 使用“"cisco-action":"activate" 密码文本是激活证书的指纹（sha-1的十六进制表示），用于设备身份验证。

  • 使用“"cisco-action":"deactivate" 密码文本是证书的指纹（sha-1的十六进制表示），我们将禁用该证书用于设备身份验证。

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

我们如何从 ClientSecret

在第一个秘密群体之后，我们不接受或输出秘密为纯文本。这是为了防止可能访问该设备的人员的潜在字典攻击。

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

这意味着您生成JWE blobs的工具必须遵循相同的程序，才能从客户端秘密中获取相同的加密/解密密钥。

设备使用 scrypt 进行密钥导出（参见 https://en.wikipedia.org/wiki/Scrypt），具有以下参数：

• 成本因子(N)为32768

• BlockSizeFactor (r)为8

• 并行因子(p)为1

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

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

• 最大内存上限为64MB

此组参数是scrypt 唯一与设备上的关键衍生功能兼容的配置。设备上的此kdf称为"version":"1"，这是cisco-kdf 参数当前唯一使用的版本。

工作示例

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

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

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

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

3. 下面是一个示例scrypt 呼叫，用于创建内容加密密钥(cek)：

   cek=scrypt(password="ossifrage", salt=4-byte-sequence, 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个字节的随机序列作为初始化向量。此示例使用(hex) 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_Y","version":"1"},"enc":"A128GCM"}

   base64url编码的JOSE标头是 eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ9

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

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

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

8. 使用JWE加密工具生成加密的有效负载和标签。在此示例中，未加密的有效负载将成为假冒的PEM blob this is a PEM file

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

   • 有效负载为 this is a PEM file

   • 加密密码为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)连接以获取：

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

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

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

    xCommand Security Certificates Add eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q