JWE 形式の使用方法

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

JSON Web Encryption（JWE） https://datatracker.ietf.org/doc/html/rfc7516 およびJSON Web Signature（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" }

    別の独自のキー。デバイスでのキーの導出のための入力としてあなたが提供する値を使用します。バージョン は1 でなければなりません(このバージョンは、鍵派生機能のバージョン)。salt の値は、base64のURLエンコードされた少なくとも4バイトのシーケンスである必要があります。このシーケンスはランダムに選択 する必要があります。

• JWE暗号化キー。フィールドが空です。このデバイスは、最初のClientSecretから取得します。

• JWE初期化ベクトル。ペイロードを解読するための base64url エンコード初期化ベクトルを提供する必要があります。IV はランダムな 12 バイト値でなければなりません (当社は AES-GCM 暗号ファミリーを使用しています。IV は 12 バイトの長さでなければなりません )。

• JWE AAD （追加認証データ）。このフィールドは、コンパクトなシリアル化でサポートされていないので、省略する必要があります。

• JWE暗号テキスト: これは、シークレットにしたい暗号化ペイロードです。

  ペイロードは空である可能性があります。たとえば、クライアントシークレットをリセットするには、空の値で上書きする必要があります。

  デバイスで行おうとしている内容に応じて、ペイロードには異なるタイプがあります。異なる xAPI コマンドは異なるペイロードを予測します。次の手順に従って、ペイロードの目的をcisco-action キーで指定する必要があります。

  • 「cisco-action」:「populate」 を使用すると、暗号テキストが新しいClientSecretになります。

  • ""cisco-action":"add" では、ciphertext は PEM ブロブで、証明書とその秘密キー (連結された) を格納します。

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

  • ""cisco-action":"deactivate" を使用すると、暗号テキストはデバイスのアイデンティティ検証に使用されないように無効化している証明書のフィンガープリント (sha-1 の 16 進数表現) です。

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

ClientSecretから暗号化キーを引き出す方法

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

デバイス ソフトウェアは、クライアント シークレットをキー導出関数 (kdf) への入力として使用し、デバイスのコンテンツの復号/暗号化のために、取得したキーを使用します。

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

デバイスは、 次のパラメータを使用して、キーの導出に 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 アルゴリズムを選択した場合) のいずれかです

• 最大メモリ上限は 64MB です

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

機能した例

次の例では、JWE 暗号化プロセスがデバイスで作成したプロセスと同じ動作を確認できます。

サンプルのシナリオは、PEM をデバイスに追加しています (完全な cert + キーの代わりに短い文字列で、証明書を追加した例です)。この例のクライアントシークレットはossifrageです。

1. 暗号化を選択します。この例では、A128GCM （Galois Counter Modeで128ビットキーを使用したAES）を使用します。必要に応じて、ツールでA256GCM を使用できます。

2. Salt を選択します (少なくとも 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 バイトのランダムシーケンスを選択して、初期化ベクトルとして使用します。この例では、（16進数）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 ブロブの最初の要素です。

6. JWE フィールドの 2 番目の要素は空です。JWE 暗号化キーを指定しないためです。

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

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

   使用すべき暗号化パラメータ:

   • ペイロードはPEMファイルです

   • 暗号化は 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. この例は実際には機能しませんが、次のステップは、上で作成した JWE グループを、証明書を追加するデバイスの xcommand への入力として使用する方法です。

    xコマンドセキュリティ証明書 eyJhbGciOiJkaXIiLCJjaXNjby1hY3Rpb24iOiJhZGQiLCJjaXNjby1rZGYiOnsic2FsdCI6IjVlWlRDQVA0TV9ZIiwidmVyc2lvbiI6IjEifSwiZW5jIjoiQTEyOEdDTSJ..9NLNd3V9Te68tkpWD.f5lLVuWNfKfmzYCo1YJfODhQ.PE-wDFWGXFFBeo928cfZ1Q