JWT ハンドブック

目次

目次　1 謝辞　4 はじめに　5 1.1 JSON Web Token とは　5 1.2 JWT が解決する問題　6 1.3 JWT の簡単な歴史　6 実際の利用例　7 2.1 クライアント側セッション/ステートレス セッション　7 2.1.1 セキュリティに関する考慮事項　8 2.1.1.1 署名の削除　8 2.1.1.2 クロスサイト リクエスト フォージェリ (CSRF)　8 2.1.1.3 クロスサイト スクリプティング (XSS)　9 2.1.2 クライアント側セッションの有用性　11 2.1.3 例　11 2.2 フェデレーション アイデンティティ　14 2.2.1 アクセス トークンとリフレッシュ トークン　15 2.2.2 JWT と OAuth2　16 2.2.3 JWT と OpenID Connect　16 2.2.3.1 OpenIDConnect のフローと JWT　16 2.2.4 例　16 2.2.4.1 Node.js アプリのための Auth0 Lock のセットアップ　17 JSON Web Token の詳細　19 3.1 ヘッダー　20 3.2 ペイロード　20 3.2.1 登録済みクレーム　21 3.2.2 パブリック クレームとプライベート クレーム　21 3.3 セキュリティ保護のない JWT　23 3.4 セキュリティ保護のない JWT の作成　23 3.4.1 サンプル コード　24 3.5 セキュリティ保護のない JWT の解析　24 3.5.1 サンプル コード　24 JSON Web Signatures　26 4.1 署名付き JWT の構造　26 4.1.1 コンパクト シリアライゼーションに使用されるアルゴリズムの概要　27 4.1.2 署名アルゴリズムの実際的な側面　28 4.1.3 JWS のヘッダー クレーム　30 4.1.4 JWS JSON シリアライゼーション　31 4.1.4.1 フラット化 JWS JSON シリアライゼーション　32 4.2 トークンの署名と検証　32 4.2.1 HS256: HMAC + SHA-256　33 4.2.2 RS256: RSASSA + SHA256　33 4.2.3 ES256: P-256 および SHA-256 を使用した ECDSA　33 JSON Web Encryption (JWE)　35 5.1 暗号化された JWT の構造　37 5.1.1 鍵暗号化アルゴリズム　37 5.1.1.1 鍵管理モード　38 5.1.1.2 コンテンツ暗号化鍵 (CEK) と JWE 暗号化鍵　39 5.1.2 コンテンツ暗号化アルゴリズム　40 5.1.3 ヘッダー　40 5.1.4 コンパクト シリアライゼーションに使用されるアルゴリズムの概要　41 5.1.5 JWE JSON シリアライゼーション　41 5.1.5.1 フラット化 JWE JSON シリアライゼーション　43 5.2 トークンの暗号化と復号　43 5.2.1 導入: node-jose を使用した鍵の管理　43 5.2.2 AES-128 Key Wrap (鍵) + AES-128 GCM (コンテンツ)　44 5.2.3 RSAES-OAEP (鍵) + AES-128 CBC + SHA-256 (コンテンツ)　45 5.2.4 ECDH-ES P-256 (鍵) + AES-128 GCM (コンテンツ)　45 5.2.5 ネストされた JWT: P-256 および SHA-256 を使用した ECDSA (署名) + RSAES-OAEP (暗号 化鍵) + AES-128 CBC + SHA-256 (暗号化コンテンツ)　45 5.2.6 復号　46 JSON Web Key (JWK)　48 6.1 JSON Web Key の構造　49 6.1.1 JSON Web Key Set　50 JSON Web Algorithms　51 7.1 一般的なアルゴリズム　51 7.1.1 Base64　51 7.1.1.1 Base64-URL　53 7.1.1.2 サンプル コード　53 7.1.2 SHA　54 7.2 署名アルゴリズム　57 7.2.1 HMAC　57 7.2.1.1 HMAC + SHA256 (HS256)　59 7.2.2 RSA　61 7.2.2.1 e、d、n の選択　62 7.2.2.2 基本的な署名方法　63 7.2.2.3 RS256: SHA-256 を使用した RSASSA PKCS1 v1.5　63 7.2.2.3.1 アルゴリズム　63 7.2.2.3.1.1 EMSA-PKCS1-v1_5 プリミティブ　65 7.2.2.3.1.2 OS2IP プリミティブ　65 7.2.2.3.1.3 RSASP1 プリミティブ　65 7.2.2.3.1.4 RSAVP1 プリミティブ　66 7.2.2.3.1.5 I2OSP プリミティブ　66 7.2.2.3.2 サンプル コード　66 7.2.2.4 PS256: SHA-256 および MGF1 と SHA-256 を使用した RSASSA-PSS71 EMSA-PSS-ENCODE プリミティブ　72

　

　 　

　　　　　　　　　　　　　　　

点の 2 倍算点の加算

7.2.2.4.1 アルゴリズム 　...................................................................................................... 71 7.2.3.1.1 7.2.3.1.2 7.2.3.1.3 点の加算 .............................................................................................................. 78 点の 2 倍算 ........................................................................................................ 78 スカラー倍算 ...................................................................................................... 79 7.2.2.4.1.1 7.2.2.4.1.2 7.2.2.4.1.3 MGF1: マスク生成関数........................................................................... 72 EMSA-PSS-ENCODE プリミティブ...................................................... 72 EMSA-PSS-VERIFY プリミティブ........................................................ 73 7.2.2.4.2 サンプル コード ................................................................................................ 75 7.2.3 楕円曲線 ................................................................................................................................................76 7.2.3.1 楕円曲線の演算.................................................................................................................. 78 7.2.3.2 楕円曲線デジタル署名アルゴリズム (ECDSA)............................................................79 7.2.3.2.1 楕円曲線のドメイン パラメーター ................................................................ 81 7.2.3.2.2 公開鍵と秘密鍵 .................................................................................................. 81 7.2.3.2.2.1 離散対数問題 ............................................................................................ 82 7.2.3.2.3 ES256: P-256 および SHA-256 を使用した ECDSA.................................... 82 7.3 今後の更新 ......................................................................................................................................................... 84 付録 A: 現在のベスト プラクティス............................................................................................................................ 85 8.1 隠れた危険とよく見られる攻撃 ..................................................................................................................... 85 8.1.1 "alg: none" 攻撃 ....................................................................................................................................86 8.1.2 RS256 公開鍵を HS256 共有シークレットとして使用する攻撃 ................................................87 8.1.3 脆弱な HMAC 鍵 ................................................................................................................................88 8.1.4 暗号化と署名検証の併用に関する誤解 ............................................................................................89 8.1.5 無効な楕円曲線による攻撃 ................................................................................................................90 8.1.6 置換攻撃 ................................................................................................................................................91 8.1.6.1 受信者が異なる場合.......................................................................................................... 91 8.1.6.2 受信者が同じ場合/Cross JWT ........................................................................................... 92 8.2 対策とベストプラクティス ............................................................................................................................. 93 8.2.1 アルゴリズムの検証を常に実行する ................................................................................................93 8.2.2 適切なアルゴリズムを使用する ........................................................................................................94 8.2.3 常にすべての検証を実行する ............................................................................................................94 8.2.4 暗号の入力を必ず検証する ................................................................................................................94 8.2.5 強力な鍵を選択する ............................................................................................................................94 8.2.6 使用可能なすべてのクレームを検証する ........................................................................................94 8.2.7 typ クレームを使用してトークンの種類を区別する ...................................................................95 8.2.8 トークンごとに異なる検証ルールを使用する ................................................................................95 8.3 まとめ ................................................................................................................................................................. 95