JWE 形式の使用方法

このセクションでは、JWE がデバイスへの入力として作成されることを期待する方法について説明します。これにより、証明書とキーからブロックを作成するための独自のツールを構築できます。

JSON ウェブ暗号化 (JWE) https://datatracker.ietf.org/doc/html/rfc7516 および JSON ウェブ署名 (JWS) https://datatracker.ietf.org/doc/html/rfc7515 を参照してください。

JSON ドキュメントのコンパクト シリアライズ を使用して、JWE ブロブを作成します。JWE ブロブを作成する際に含める必要があるパラメータは次のとおりです。

• JOSE ヘッダー (保護)。JSON オブジェクトの署名と暗号化ヘッダーには、次のキーと値のペアを含める必要があります。

  • "alg":"dir"

    ダイレクト アルゴリズムは、ペイロードの暗号化をサポートする唯一のものであり、デバイスの初期クライアント シークレットを使用する必要があります。

  • "enc":"A128GCM" または "enc":"A256GCM"

    これらの 2 つの暗号化アルゴリズムをサポートしています。

  • "cisco-action": "add" または "cisco-action": "populate" または "cisco-action": "activate" または "cisco-action": "deactivate"

    これは独自のキーであり、取ることができる 4 つの値です。このキーを導入して、暗号化されたデータの目的をターゲットデバイスに知らせます。値は、暗号化されたデータを使用しているデバイスの xAPI コマンドにちなんで命名されます。

    今後の JWE 拡張機能との潜在的な衝突を軽減するために、cisco-action この名前を付けました。

  • "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 ブロブです。

  • 「"cisco-action":"activate" 暗号テキストは、デバイス ID 検証のためにアクティベートしている証明書のフィンガープリント (sha-1 の 16 進数表現) です。

  • 「"cisco-action":"deactivate" 暗号テキストは証明書のフィンガープリント (sha-1 の 16 進数表現) であり、デバイス ID 検証に使用されなくなっています。

• JWE 認証タグ: このフィールドには、JWE のコンパクトにシリアライズされた blob 全体の整合性を確認するための認証タグが含まれます。

暗号化キーを ClientSecret

シークレットの最初の集団の後、私たちはシークレットをプレーンテキストとして受け入れまたは出力しません。これは、デバイスにアクセスできる人による辞書攻撃を防ぐためです。

デバイス ソフトウェアは、クライアント シークレットをキー導出機能（kdf）への入力として使用し、デバイスのコンテンツの復号/暗号化に派生キーを使用します。

これは、JWE ブロブを生成するツールが同じ手順に従い、クライアント シークレットから同じ暗号化/復号キーを導き出す必要があります。

デバイスは、次のパラメータを使用して、キーの導出に scrypt を使用します (https://en.wikipedia.org/wiki/Scryptを参照)。

• CostFactor (N) は 32768 です

• BlockSizeFactor (r) は 8 です

• ParallelizationFactor (p) は 1 です

• salt は少なくとも 4 バイトのランダムシーケンスです。salt パラメータを指定する場合はcisco-kdf 同じ値を指定する必要があります。

• キーの長さは 16 バイト（AES-GCM 128 アルゴリズムを選択した場合）、または 32 バイト（AES-GCM 256 アルゴリズムを選択した場合）。

• 最大メモリ容量は 64MB です

このパラメータのセットは、デバイスのキー導出機能と互換性がある scrypt の唯一の構成です。デバイス上のこの kdf は "version":"1" と呼ばれ、cisco-kdf パラメータによって現在使用されている唯一のバージョンです。

成功した例

以下は、JWE 暗号化プロセスがデバイスで作成したプロセスと同じ動作であることを確認するための例です。

この例のシナリオでは、PEM ブロブをデバイスに追加しています（証明書を追加することを模倣し、完全な証明書とキーの代わりに非常に短い文字列を使用します）。この例のクライアント シークレットは ossifrage です。

1. 暗号化を選択します。この例では、A128GCM を使用します (Galois カウンター モードで 128 ビット キーを持つ AES)。必要に応じて、ツールを使用できますA256GCM 。

2. ソルト (少なくとも 4 バイトのランダムシーケンスである必要があります) を選択します。この例では (16 バイト)E5 E6 53 08 03 F8 33 F6 を使用します。Base64url はシーケンスをエンコードして 5eZTCAP4M_Y (base64 パディングを削除) を取得します。

3. コンテンツ暗号化キー (cek) を作成するためのサンプルscrypt コールの例を次に示します。

   cek=scrypt(password="ossifrage", salt=4-byte-sequence, N=32768, r=8, p=1, keylength=16)

   取得されたキーは、次のように 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 にエンコードする (16 進数) を使用します。

5. コンパクトなシリアライゼーションで JOSE ヘッダーを作成し (ここで使用するパラメータの同じ順序に従います)、base64url エンコードします。

   {"alg":"dir","cisco-action":"add","cisco-kdf":{"salt":"5eZTCAP4M_Y","version":"1"},"enc":"A128GCM"}

   base64url エンコードされた JOSE ヘッダーは eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ9

   これは JWE ブロブの最初の要素になります。

6. JWE 暗号化キーを提供していないため、JWE ブロブの 2 番目の要素は空です。

7. JWE ブロブの 3 番目の要素は、初期化ベクトル NLNd3V9Te68tkpWD です。

8. JWE 暗号化ツールを使用して、暗号化ペイロードとタグを生成します。この例では、暗号化されていないペイロードは偽の PEM ブロブになります。 this is a PEM file

   使用する暗号化パラメータは次のとおりです。

   • ペイロードは です this is a PEM file

   • 暗号化は AES 128 GCM です

   • base64url は、追加の認証データ（AAD）として JOSE ヘッダーをエンコードしました

   Base64url は暗号化されたペイロードをエンコードし、結果として f5lLVuWNfKfmzYCo1YJfODhQ

   これは JWE ブロブの 4 番目の要素（JWE Ciphertext）です。

9. ステップ 8 で生成したタグを Base64url エンコードします。結果として PE-wDFWGXFFBeo928cfZ1Q

   これは JWE ブロブの 5 番目の要素です。

10. JWE ブロブの 5 つの要素をドット（JOSEheader..IV.Ciphertext.Tag）で連結して、以下を取得します。

    eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q

11. 独自のツールを使用して、ここに示されているのと同じ base64url エンコード値を取得した場合、それらを使用して、デバイスの E2E 暗号化と検証済みの ID を保護することができます。

12. この例は実際には機能しませんが、次のステップは、証明書を追加するデバイスの xcommand への入力として上記で作成した JWE ブロブを使用することです。

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