如何使用 JWE 格式

本節說明我們預期如何將 JWE 建立為裝置輸入，以便您可以建立您自己的工具，以從憑證和金鑰建立 Blob。

請參閱JSON 網路加密 (JWE) https://datatracker.ietf.org/doc/html/rfc7516 和JSON網路簽名 (JWS) https://datatracker.ietf.org/doc/html/rfc7515 。

我們使用精簡序列化 的 JSON 文件以建立 JWE Blob。建立 JWE Blob 時需要包括的參數是：

• JOSE 標頭 （受保護）。在 JSON 物件簽署和加密標頭中，您必須包含下列金鑰值組：

  • 「alg」：「目錄」

    直接演算法是我們支援用於加密裝載的唯一演算法，且您必須使用裝置的初始用戶端密碼。

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

    我們支援這兩種加密演算法。

  • "cisco-action": "新增" 或"cisco-action": "填入" 或"cisco-action": "啟用" 或"cisco-action": "停用"

    這是專屬金鑰，且可以使用四個值。我們引進了此金鑰來向目標裝置發出加密資料用途的訊號。這些值是以使用加密資料裝置上的 xAPI 指令命名。

    我們將其命名cisco-action 以減輕與未來的 JWE 擴充功能的潛在衝突。

  • "cisco-kdf": { "version": "1", "salt": "base64URLEncodeRandom4+字節" }

    另一個專屬金鑰。我們使用您提供的值當做裝置上金鑰衍生的輸入。的版本 必須是1 （我們的金鑰推導功能的版本）。的值鹽 必須是至少 4 個字節的 base64 URL編碼序列，您可以必須 隨機選擇。

• JWE 加密金鑰。此欄位為空。該裝置從初始的用戶端機密。

• JWE 初始化向量。您必須提供 base64url 編碼的初始化向量以解密裝載。IV 必須是隨機的 12 位元組值（我們使用的是 AES-GCM 加密系列，要求 IV 長度為 12 位元組）。

• JWE AAD （其他經過驗證的資料）。您必須省略此欄位，因為其在精簡序列化中不受支援。

• JWE 密文：這是您想要保密的加密裝載。

  有效荷載可能為空。例如，若要重設用戶端密碼，您需要使用空值來覆寫它。

  存在不同類型的裝載，取決於您嘗試在裝置上執行什麼操作。不同的 xAPI 指令預期不同的有效荷載，您必須使用下列字元指定有效荷載的用途： cisco-action 鍵，如下所示：

  • 有"cisco-action":"填入" 密文是新的用戶端機密。

  • 有了 " "cisco-action":"新增" 密文是帶有憑證及其私密金鑰（串聯）的 PEM Blob。

  • 有了 " "cisco-action":"啟用" 密文是我們為裝置身分驗證而啟動的憑證的指紋（sha-1 的十六進製表示）。

  • 有了 " "cisco-action":"停用" 密文是我們要停用的憑證的指紋（sha-1 的十六進製表示），以免其用於裝置身分驗證。

• JWE 驗證標籤： 此欄位包含驗證標籤，用於驗證 JWE 壓縮序列化 Blob 的完整性

我們如何從用戶端機密

在填入第一個密碼之後，我們不接受或輸出純文字密碼。這是為了防止可能會由可存取裝置的人員進行字典攻擊。

裝置軟體會使用用戶端密碼作為金鑰衍生功能 (kdf) 的輸入，然後使用衍生的金鑰在裝置上解密/加密。

這對您而言表示您產生 JWE Blob 的工具必須遵循相同的程序，從用戶端密碼衍生相同的加密/解密金鑰。

裝置會使用 scrypt 來金鑰衍生（請參閱 https://en.wikipedia.org/wiki/Scrypt），並包含以下參數：

• CostFactor (N) 為 32768

• BlockSizeFactor (r) 為 8

• ParallelizationFactor (p) 為 1

• Salt 是至少 4 個位元組的隨機序列；您必須提供相同的鹽 當指定思科-kdf 參數。

• 金鑰長度為 16 位元組（如果您選取 AES-GCM 128 演算法）或 32 位元組（如果您選取 AES-GCM 256 演算法）

• 最大記憶體容量為 64MB

這組參數是裝置上唯一與金鑰衍生功能相容的 scrypt 設定。裝置上的這個 kdf 稱為「版本」：「1」 ，這是目前使用的唯一版本思科-kdf 參數。

運作範例

您可以遵循以下範例來驗證您的 JWE 加密程序是否與我們在裝置上建立的程序相同。

範例情境是將 PEM Blob 新增至裝置（模仿使用極短字串而非完整的憑證 + 金鑰來新增憑證）。範例中的用戶端密碼為保留。

1. 選擇加密密碼。此範例使用A128GCM （在伽羅瓦計數器模式中使用 128 位元金鑰的AES ）。您的工具可以使用A256GCM 如果您願意。

2. 選擇一個 salt（必須是至少 4 位元組的隨機序列）。此範例使用 （16 位元組） E5 E6 53 08 03 F8 33 F6 。Base64url 對序列進行編碼以獲取5eZTCAP4M_是 （移除 base64 填充）。

3. 這是一個範例scrypt 建立內容加密金鑰(cek) 的呼叫：

   cek=scrypt（密碼="ossifage"，鹽 = 4 字節序列，N = 32768，r = 8，p = 1，密鑰長度 = 16）

   衍生的金鑰應該為 16 位元組（十六進位），如下所示：95 9e ba 6d d1 22 01 05 78 fe 6a 9d 22 78 ff ac base64url 編碼為lZ66bdEiAQV4_mqd我nj_r一個。

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_ Y","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) 以取得：

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

11. 如果您衍生了與這裡所顯示相同的 base64url 編碼值，則您可以使用您自己的工具來保護您裝置的 E2E 加密和經過驗證的身分。

12. 此範例實際上不起作用，但原則上，您的下一步是使用您上面所建立的 JWE Blob 新增憑證的裝置上 xcommand 的輸入：

    xCommand 安全性憑證新增 eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q