+ {t({ + en: "604800 seconds is seven days, the ceiling S3 allows, because the signing key itself is only valid that long.", + ja: "604800 秒は 7 日で、S3 が認める上限です。署名キー自体がその期間しか有効でないためです。", + })} +
+ )} + {r ? ( +
+ {r.url.replace(/&/g, "\n &")}
+
+ + {t({ + en: "Nothing else is needed to use it: no header, no SDK, no key. Whoever holds this string is the caller until it expires, which is why a presigned URL in a log or a chat message is a credential leak.", + ja: "使うのに他は何も要りません。ヘッダーも SDK もキーも不要です。この文字列を持っている人が期限まで呼び出し元になります。ログやチャットに貼られた presigned URL がそのまま認証情報の漏洩になるのはそのためです。", + })} +
+
+ {r.canonicalRequest}
+
+ + {rich( + t({ + en: "The last line is the literal `UNSIGNED-PAYLOAD`, because at signing time nobody knows what will be uploaded. A presigned PUT therefore pins the destination, not the bytes.", + ja: "最終行は文字列 `UNSIGNED-PAYLOAD` そのものです。署名の時点では何がアップロードされるか分からないからです。つまり presigned な PUT が保証するのは宛先であって、中身ではありません。", + }), + )} +
++ {rich( + t({ + en: "With temporary credentials the session token goes into the query string as `X-Amz-Security-Token` and is signed there, not as a header.", + ja: "一時認証情報の場合、セッショントークンはヘッダーではなくクエリ文字列の `X-Amz-Security-Token` に入り、そこで署名対象になります。", + }), + )} +
+
+ {r.credentialScope}
+
+ + {rich( + t({ + en: "No Region. SigV4 would read `20260919/us-east-1/s3/aws4_request` here; SigV4a states the Regions in the `X-Amz-Region-Set` header instead, which is itself signed.", + ja: "リージョンがありません。SigV4 ならここは `20260919/us-east-1/s3/aws4_request` になります。SigV4a ではリージョンを `X-Amz-Region-Set` ヘッダーで示し、そのヘッダー自体が署名対象になります。", + }), + )} +
+
+ {`private ${r.keyPair.privateKeyHex}\npublic ${r.keyPair.publicKeyHex}\ncounter ${r.keyPair.counter}`}
+
+ + {t({ + en: "The secret key is run through a counter-mode KDF until the result lands inside the P-256 group order. A 256-bit value can exceed the order, so the counter is not decorative, though in practice the first candidate works. No new credential is issued: AWS derives the same public key on its side when it checks a signature.", + ja: "シークレットキーを counter モードの KDF に通し、結果が P-256 の位数に収まるまで繰り返します。256 ビットの値は位数を超えることがあるので counter は飾りではありませんが、実際には最初の候補で通ります。新しい認証情報は発行されません。AWS は署名を検証するとき、自分の側で同じ公開鍵を導出します。", + })} +
+
+ {r.stringToSign}
+
+ + {t({ + en: "Reproducible here because this implementation uses the RFC 6979 deterministic nonce. AWS SDKs sign through libcrypto and produce different bytes for the same request. Both verify; only one is reproducible.", + ja: "この実装は RFC 6979 の決定的 nonce を使うので、毎回同じ結果になります。AWS SDK は libcrypto 経由で署名するため、同じリクエストでも毎回バイト列が変わります。どちらも検証は通り、再現できるのは片方だけです。", + })} +
+{rich(t(note))}
} +
+ {body}
+
+ {rich(t(n.detail))}
+{rich(t(demo.blurb))}
++ {t({ + en: "Date, Region and service are baked into the key. A leaked signing key works for that day, that Region and that service, and nothing else.", + ja: "日付・リージョン・サービスがキーに焼き込まれます。署名キーが漏れても、その日・そのリージョン・そのサービスにしか使えません。", + })} +
++ {{ + en: "Every credential passes through four stages: **issue** (IAM or STS hands it out), **sign** (your code turns it into a signature), **verify** (the service recomputes the signature) and **authorize** (only then are policies evaluated). The unsigned `AssumeRoleWithWebIdentity` and `AssumeRoleWithSAML` calls never reach the sign stage: the token in the body is the proof. A bearer token skips issue and sign both.", + ja: "認証情報は 4 つの段階を通ります。**発行** (IAM か STS が渡す)、**署名** (自分のコードが署名に変える)、**検証** (サービスが署名を計算し直す)、**認可** (ここで初めてポリシーが評価される) です。署名のない `AssumeRoleWithWebIdentity` と `AssumeRoleWithSAML` は署名の段階を通りません。ボディのトークンが証明そのものです。bearer トークンは発行と署名の両方を飛ばします。", + }} +
++ {{ + en: "A long-term key is the only AWS credential with no expiration. IAM stores the secret so it can recompute signatures later, and shows it to you exactly once. An IAM user can hold two access keys at a time, Active or Inactive; asking for a third returns `LimitExceeded`. Two is what makes rotation possible: create the new one, move traffic, delete the old one.", + ja: "長期キーは有効期限のない唯一の AWS 認証情報です。IAM は後で署名を再計算するためにシークレットを保管し、利用者には一度だけ表示します。IAM ユーザーが同時に持てるアクセスキーは Active・Inactive を問わず 2 本までで、3 本目を求めると `LimitExceeded` が返ります。2 本あるからローテーションが成り立ちます。新しいキーを作り、トラフィックを移し、古いキーを消します。", + }} +
++ {{ + en: "A **presigned URL** is the same signature moved out of the headers and into the query string. That turns it into a bearer token: whoever holds the URL can make that one request until it expires, with no key and no IAM identity of their own.", + ja: "**presigned URL** は、同じ署名をヘッダーからクエリ文字列に移したものです。その結果、bearer トークンになります。URL を持っている人は、キーも自分の IAM ID もなしに、期限までその 1 つのリクエストを実行できます。", + }} +
++ {{ + en: "A SigV4 signing key is scoped to one Region by construction. **SigV4a** moves that scoping elsewhere so one signature can be valid in several Regions, which is what S3 Multi-Region Access Points need; SDKs and the CLI switch to it automatically for them. It signs with an ECDSA P-256 key derived from the same secret, so verifying needs only the public half, and that can be replicated freely. SigV4 verification needs the shared secret, so every Region that verifies must hold it.", + ja: "SigV4 の署名キーは構造上 1 つのリージョンに固定されます。**SigV4a** はその固定を別の場所に移し、1 つの署名を複数のリージョンで有効にします。S3 マルチリージョンアクセスポイントに必要な仕組みで、SDK と CLI はその宛先に対して自動で切り替えます。同じシークレットから導出した ECDSA P-256 鍵で署名するので、検証には公開鍵だけあればよく、それは自由に複製できます。SigV4 の検証には共有シークレットが要るので、検証するリージョンはすべてそれを持つ必要があります。", + }} +
++ {{ + en: "**Amazon Bedrock API keys** are the one AWS path that skips SigV4 entirely: one `Authorization: Bearer` header, no canonical request, no signing key, no SDK required. They exist for tools that expect an API key and cannot be taught to sign. Short-term keys last up to 12 hours (or the session, if shorter) and work only in the Region they were generated in; long-term keys last until a configured expiry and are tied to an IAM user.", + ja: "**Amazon Bedrock の API キー** は、SigV4 を丸ごと飛ばす AWS で唯一の経路です。`Authorization: Bearer` ヘッダー 1 つだけで、正規リクエストも署名キーも SDK も要りません。API キーを前提にしていて署名を組み込めないツールのためにあります。短期キーは最長 12 時間 (セッションの方が短ければそれまで) で、生成したリージョンでしか使えません。長期キーは設定した期限まで有効で、IAM ユーザーに紐づきます。", + }} +
++ {{ + en: "How the signer is checked: CI asserts it byte for byte against two worked examples AWS publishes, the Glacier Create Vault signature (canonical request, string to sign and signature) and the S3 presigned `test.txt` URL. SigV4a has no AWS-published vector, so its derived keys are cross-checked against an independent implementation of the published pseudocode instead, which is weaker evidence. One of the Glacier page's own examples does not reproduce; the notes record how that was ruled out.", + ja: "署名処理の確かめ方: CI で、AWS が公開している 2 つの計算例とバイト単位で照合しています。Glacier の Create Vault の署名 (正規リクエスト・署名対象文字列・署名) と、S3 の presigned `test.txt` の URL です。SigV4a には AWS 公開のテストベクタがないので、公開された疑似コードを別に実装したものと導出結果を突き合わせています。こちらは証拠としては弱めです。Glacier のページにある別の例は再現できず、その切り分けの経緯は調査メモに残しています。", + }} +
+ +
+
+ {annotate(text, annotations, active, setActive)}
+
+ {picked && (
+ + {rich(t(picked.note))} +
+ )} +
{t({
- en: "How the signature itself is computed is drawn step by step in the sibling project ",
- ja: "署名そのものの計算は、姉妹プロジェクト ",
+ en: "How the signature itself is computed, and broken, is worked through live in chapter ",
+ ja: "署名そのものの計算 (と壊し方) は、第 ",
})}
-
{t({ - en: "604800 seconds is seven days, the ceiling S3 allows, because the signing key itself is only valid that long.", - ja: "604800 秒は 7 日で、S3 が認める上限です。署名キー自体がその期間しか有効でないためです。", + en: "604800 seconds is seven days, the most the CLI and SDKs allow. A URL signed with temporary credentials stops working when they expire anyway, whatever X-Amz-Expires says.", + ja: "604800 秒は 7 日で、CLI と SDK で設定できる上限です。一時認証情報で署名した URL は、X-Amz-Expires に関係なく、その認証情報が失効した時点で使えなくなります。", })}
)} diff --git a/src/features/signing/sigv4.ts b/src/features/signing/sigv4.ts index e257f80..59258af 100644 --- a/src/features/signing/sigv4.ts +++ b/src/features/signing/sigv4.ts @@ -214,7 +214,7 @@ async function finishSignature( } export interface PresignOptions extends SigV4Options { - /** Seconds the URL stays valid. S3 caps this at 604800 (seven days). */ + /** Seconds the URL stays valid. The CLI and SDKs allow up to 604800 (seven days). */ expiresIn: number; } From 26dc64de112f3c3c4eef7873d03c5a782767a31a Mon Sep 17 00:00:00 2001 From: kanywst <45947799+kanywst@users.noreply.github.com> Date: Sun, 8 Nov 2026 11:30:15 +0900 Subject: [PATCH 3/5] docs(signing): correct Lambda delivery, scope the no-expiry claim and soften unsourced claims --- docs/signing/01-credential-map.ja.md | 6 +++--- docs/signing/01-credential-map.md | 10 ++++++---- docs/signing/03-federation.ja.md | 2 +- docs/signing/03-federation.md | 3 ++- docs/signing/04-variants.ja.md | 2 +- docs/signing/04-variants.md | 7 ++++--- docs/signing/05-verification.ja.md | 2 +- docs/signing/05-verification.md | 2 +- src/features/signing/SigV4aLab.tsx | 4 ++-- src/features/signing/sigv4a.test.ts | 8 ++++---- 10 files changed, 25 insertions(+), 21 deletions(-) diff --git a/docs/signing/01-credential-map.ja.md b/docs/signing/01-credential-map.ja.md index 2c6efab..1d49510 100644 --- a/docs/signing/01-credential-map.ja.md +++ b/docs/signing/01-credential-map.ja.md @@ -13,9 +13,9 @@ AWS の API を呼ぶという目的に限れば、形は2つだけ。それに | --- | --- | --- | --- | | 長期キー | `AKIA...` + secret | `iam:CreateAccessKey` | 無し | | 一時クレデンシャル | `ASIA...` + secret + session token | STS | 必ずある | -| bearer token | 不透明な文字列1本 | Bedrock, CloudWatch | 種類による | +| bearer token | 不透明な文字列1本 | Bedrock の API キー | 種類による | -長期キーは、期限を持たない唯一の AWS API クレデンシャル。このページに書く残り全部は、その1点から +SigV4 のキーペアの中で、期限を持たないのは長期キーだけ (長期の Bedrock API キーは作成時に決めた期限まで有効で、専用の IAM user に紐づく)。このページに書く残り全部は、その1点から 派生している。 ## 入り口の問題 @@ -55,7 +55,7 @@ IMDS は別のやり方で循環を断つ。プラットフォームが既に As 途中の1ステップ。 - **OIDC フェデレーション。** CI から長期キーを消す。仕事をしているのは trust policy で、そこを 間違える話は [フェデレーション](03-federation.ja.md) で扱う。 -- **IMDS。** EC2 や Lambda のディスクに何も置かなくてよい理由。IMDSv2 の `PUT` は趣味ではない。SSRF +- **IMDS。** EC2 のディスクに何も置かなくてよい理由 (Lambda は同じ 3 つの値を環境変数で、ECS や EKS Pod Identity はコンテナ用エンドポイントで受け取る)。IMDSv2 の `PUT` は趣味ではない。SSRF は脆弱なアプリから `GET` を引き出せても、カスタムヘッダ付きの `PUT` はまず引き出せない。 - **bearer token。** API キーを期待していて署名を教え込めないツール向け。AWS 自身の案内も「STS が 不可能な場合に限れ」。 diff --git a/docs/signing/01-credential-map.md b/docs/signing/01-credential-map.md index fb7ec99..141c611 100644 --- a/docs/signing/01-credential-map.md +++ b/docs/signing/01-credential-map.md @@ -13,10 +13,11 @@ and does not fit either. | --- | --- | --- | --- | | Long-term key | `AKIA...` + secret | `iam:CreateAccessKey` | Never | | Temporary credential | `ASIA...` + secret + session token | STS | Yes, always | -| Bearer token | One opaque string | Bedrock, CloudWatch | Depends | +| Bearer token | One opaque string | Bedrock API keys | Depends | -The long-term key is the only AWS API credential with no expiry. That single property is -the reason for everything else on this page. +Among the SigV4 key pairs, the long-term key is the only one with no expiry. That single +property is the reason for everything else on this page. (A long-term Bedrock API key lasts +until the expiry configured at creation, and is tied to an IAM user of its own.) ## The entry problem @@ -56,7 +57,8 @@ leaves the result on a link-local address. already, so it is a step in a chain rather than an entry point. - **OIDC federation.** Ends long-term keys in CI. The trust policy does the work, and getting it wrong is the subject of [Federation](03-federation.md). -- **IMDS.** Why an EC2 instance or a Lambda needs nothing on disk. The `PUT` in IMDSv2 is +- **IMDS.** Why an EC2 instance needs nothing on disk. (Lambda gets the same three values + as environment variables instead, and ECS and EKS Pod Identity from a container endpoint.) The `PUT` in IMDSv2 is not stylistic: server-side request forgery can usually coerce a `GET` out of a vulnerable application, rarely a `PUT` carrying a custom header. - **Bearer tokens.** For tools that expect an API key and cannot be taught to sign. AWS's diff --git a/docs/signing/03-federation.ja.md b/docs/signing/03-federation.ja.md index 33ec835..a2885ea 100644 --- a/docs/signing/03-federation.ja.md +++ b/docs/signing/03-federation.ja.md @@ -107,7 +107,7 @@ STS が欲しいのは身元の主張なので、ID token が正しい形。こ このロールを assume できる。 2. **`repo:*` や裸の `*`。** 制約に見える。GitHub 上の全リポジトリに一致する。 3. **`repo:my-org/*`。** これは狭いが、特定の意味でまだ間違っている。後から org に追加された - リポジトリを含み、乗っ取られたアカウントが作ったものも含み、pull request と fork を区別しない。 + リポジトリを含み、乗っ取られたアカウントが作ったものも含み、トリガーも区別しない。`pull_request` の実行 (`sub` が `:pull_request` で終わる) が `main` への push (`:ref:refs/heads/main`) と同じロールを得る。 4. **`Action` に `sts:AssumeRole` と書く。** 呼び出す API 名がそのまま policy に書くべき `Action` 名 になる。OIDC なら `sts:AssumeRoleWithWebIdentity`、SAML なら `sts:AssumeRoleWithSAML`。これは fail closed なので、4つの中では一番害が小さい。 diff --git a/docs/signing/03-federation.md b/docs/signing/03-federation.md index 3d4721e..da9a039 100644 --- a/docs/signing/03-federation.md +++ b/docs/signing/03-federation.md @@ -113,7 +113,8 @@ Four recurring mistakes, in rough order of how often they appear. GitHub. 3. **`repo:my-org/*`.** Narrower, and still wrong in a specific way: it covers repositories added to the org later, including ones created by a compromised account, - and it does not distinguish a pull request from a fork. + and it matches every trigger, so a `pull_request` run (`sub` ending in `:pull_request`) + gets the same role as a push to `main` (`:ref:refs/heads/main`). 4. **`sts:AssumeRole` written as the `Action`.** The API you call is the `Action` the policy must name. OIDC needs `sts:AssumeRoleWithWebIdentity`, SAML needs `sts:AssumeRoleWithSAML`. This one fails closed, which makes it the least dangerous of diff --git a/docs/signing/04-variants.ja.md b/docs/signing/04-variants.ja.md index 46ec932..22dda3f 100644 --- a/docs/signing/04-variants.ja.md +++ b/docs/signing/04-variants.ja.md @@ -120,5 +120,5 @@ WebCrypto だけでは実装できない。公開鍵の導出には「自分で このリポジトリは `@noble/curves` を使っている。 1つ書いておく価値のある帰結。`@noble/curves` は RFC 6979 の決定的 nonce が既定なので、ここでは同じ -リクエストに2回署名すると同じバイト列になる。AWS SDK は libcrypto 経由なのでそうならない。どちらも +リクエストに2回署名すると同じバイト列になる。SDK の署名処理は一般に乱数の nonce を使うので、そうはならない (SDK ごとには未検証)。どちらも 検証は通り、再現するのは一方だけ。SigV4a の署名に固定テストベクタを書こうとすると、ここが効いてくる。 diff --git a/docs/signing/04-variants.md b/docs/signing/04-variants.md index 63b033b..b9ac920 100644 --- a/docs/signing/04-variants.md +++ b/docs/signing/04-variants.md @@ -127,6 +127,7 @@ point by a scalar you chose, and `SubtleCrypto` exposes no scalar multiplication curve arithmetic has to come from a library. This repository uses `@noble/curves`. One consequence worth stating: `@noble/curves` defaults to the RFC 6979 deterministic -nonce, so signing the same request twice here gives identical bytes. AWS SDKs sign through -libcrypto and will not. Both verify; only one is reproducible, which matters if you ever -try to write a fixed test vector for a SigV4a signature. +nonce, so signing the same request twice here gives identical bytes. SDK signers typically +use a randomised nonce and will not (unverified per SDK). Both verify; only one is +reproducible, which matters if you ever try to write a fixed test vector for a SigV4a +signature. diff --git a/docs/signing/05-verification.ja.md b/docs/signing/05-verification.ja.md index cc4e1e8..d1a304e 100644 --- a/docs/signing/05-verification.ja.md +++ b/docs/signing/05-verification.ja.md @@ -66,7 +66,7 @@ Glacier の署名ページには2つ目の例、streaming の `Upload Archive` **SigV4a の署名。** 原理的に固定できない。ECDSA は乱数を使う。代わりに、署名が導出した公開鍵で検証 できることを assert している。これは AWS が実際に行う検証と同じ。(この実装は `@noble/curves` の既定に -より RFC 6979 で決定的になるが、AWS 側はそうではない。) +より RFC 6979 で決定的になる。SDK 側は一般にそうではないが、SDK ごとには未検証。) ## レビューで見つかった誤り diff --git a/docs/signing/05-verification.md b/docs/signing/05-verification.md index 5419312..864267d 100644 --- a/docs/signing/05-verification.md +++ b/docs/signing/05-verification.md @@ -74,7 +74,7 @@ transcription slips; it does not rule out both having read the prose the same wr **SigV4a signatures.** Not pinnable in principle: ECDSA is randomised. What is asserted instead is that a signature verifies against the derived public key, which is the check AWS performs. (This implementation happens to be deterministic because `@noble/curves` -defaults to RFC 6979; AWS's is not.) +defaults to RFC 6979; SDK signers typically are not, though that is unverified per SDK.) ## Corrections found while reviewing diff --git a/src/features/signing/SigV4aLab.tsx b/src/features/signing/SigV4aLab.tsx index 884876c..384a226 100644 --- a/src/features/signing/SigV4aLab.tsx +++ b/src/features/signing/SigV4aLab.tsx @@ -136,8 +136,8 @@ export function SigV4aLab() {{t({ - en: "Reproducible here because this implementation uses the RFC 6979 deterministic nonce. AWS SDKs sign through libcrypto and produce different bytes for the same request. Both verify; only one is reproducible.", - ja: "この実装は RFC 6979 の決定的 nonce を使うので、毎回同じ結果になります。AWS SDK は libcrypto 経由で署名するため、同じリクエストでも毎回バイト列が変わります。どちらも検証は通り、再現できるのは片方だけです。", + en: "Reproducible here because this implementation uses the RFC 6979 deterministic nonce. SDK signers typically use a randomised nonce, so the same request gives different bytes each time. Both verify; only one is reproducible.", + ja: "この実装は RFC 6979 の決定的 nonce を使うので、毎回同じ結果になります。SDK の署名処理は一般に乱数の nonce を使うので、同じリクエストでも毎回バイト列が変わります。どちらも検証は通り、再現できるのは片方だけです。", })}
diff --git a/src/features/signing/sigv4a.test.ts b/src/features/signing/sigv4a.test.ts index 4a6baad..5b2c909 100644 --- a/src/features/signing/sigv4a.test.ts +++ b/src/features/signing/sigv4a.test.ts @@ -23,8 +23,8 @@ import { * The signature is a separate matter. ECDSA is randomised in general, so a * SigV4a signature is not something a vendor could publish as a fixed vector * anyway. @noble/curves happens to default to the deterministic RFC 6979 nonce, - * which makes ours reproducible, but AWS's own implementations sign through - * libcrypto and theirs will not be. What is portable across both is that the + * which makes ours reproducible, while SDK signers typically use a randomised + * nonce (unverified per SDK). What is portable across both is that the * signature verifies against the derived public key, which is the check AWS * actually performs. */ @@ -205,8 +205,8 @@ describe("signing", () => { const b = await signSigV4a(canonicalRequest, AWS_EXAMPLE, "host", options); // Worth stating rather than assuming: ECDSA is randomised in general, and - // AWS's own implementations sign through libcrypto, so the same request - // signed twice by an AWS SDK will not produce identical bytes. @noble's + // SDK signers typically use a randomised nonce, so the same request signed + // twice by an SDK is not expected to produce identical bytes. @noble's // default is the deterministic RFC 6979 nonce, so ours does. Both verify; // only one is reproducible. expect(a.signature).toBe(b.signature); From e812574ab98f31963e077411371a4e01db3f50b1 Mon Sep 17 00:00:00 2001 From: kanywst <45947799+kanywst@users.noreply.github.com> Date: Sun, 8 Nov 2026 11:34:14 +0900 Subject: [PATCH 4/5] docs(signing): fix GetSessionToken/GetFederationToken ceilings and drop the unsourced SDK nonce claim --- docs/signing/03-federation.ja.md | 8 ++++---- docs/signing/03-federation.md | 8 ++++---- docs/signing/04-variants.ja.md | 2 +- docs/signing/04-variants.md | 8 ++++---- docs/signing/05-verification.ja.md | 2 +- docs/signing/05-verification.md | 2 +- docs/signing/README.ja.md | 4 ++-- docs/signing/README.md | 2 +- src/features/signing/SigV4aLab.tsx | 4 ++-- src/features/signing/sigv4a.test.ts | 11 ++++------- 10 files changed, 24 insertions(+), 27 deletions(-) diff --git a/docs/signing/03-federation.ja.md b/docs/signing/03-federation.ja.md index a2885ea..bc50dd6 100644 --- a/docs/signing/03-federation.ja.md +++ b/docs/signing/03-federation.ja.md @@ -4,9 +4,9 @@ [ノートに戻る](README.ja.md) -## 6つの発行 API +## 古典的な 6 つの発行 API -STS は単一の関数ではない。クレデンシャルを返すのは次の操作。 +STS は単一の関数ではない。従来型の 3 点セットのクレデンシャルを返すのは次の 6 操作。アウトバウンドフェデレーション用の `GetWebIdentityToken` を含む STS の全 11 操作は [API operations](../03-api-operations.md) にある。 | API | 入り口の条件 | 上限 | | --- | --- | --- | @@ -14,8 +14,8 @@ STS は単一の関数ではない。クレデンシャルを返すのは次の | `AssumeRoleWithSAML` | SAML assertion、**AWS クレデンシャル不要** | 同上 | | `AssumeRoleWithWebIdentity` | OIDC ID token、**AWS クレデンシャル不要** | 同上 | | `AssumeRoot` | 管理アカウント | 固定15分 | -| `GetSessionToken` | IAM user のキー、必要なら MFA | 12時間 | -| `GetFederationToken` | IAM user のキー | 12時間 | +| `GetSessionToken` | IAM user のキー、必要なら MFA | 36時間 (既定12時間、root user は1時間) | +| `GetFederationToken` | IAM user のキー | 36時間 (既定12時間、root user は1時間) | `AssumeRole` の `DurationSeconds` は900秒以上で、ロールの `MaxSessionDuration` が上限。その `MaxSessionDuration` 自体は1〜12時間で設定できる。既定は3600秒。assume したロールからさらに assume diff --git a/docs/signing/03-federation.md b/docs/signing/03-federation.md index da9a039..0595e31 100644 --- a/docs/signing/03-federation.md +++ b/docs/signing/03-federation.md @@ -4,9 +4,9 @@ [Back to notes](README.md) -## The six issuance APIs +## The six classic issuance APIs -STS is not one function. These are the operations that hand back credentials. +STS is not one function. These six are the operations that hand back the classic three-part credential; the full list of all 11 STS operations, including `GetWebIdentityToken` for outbound federation, is in [API operations](../03-api-operations.md). | API | Entry requirement | Ceiling | | --- | --- | --- | @@ -14,8 +14,8 @@ STS is not one function. These are the operations that hand back credentials. | `AssumeRoleWithSAML` | A SAML assertion, **no AWS credential** | Same | | `AssumeRoleWithWebIdentity` | An OIDC ID token, **no AWS credential** | Same | | `AssumeRoot` | Management account | Fixed 15 minutes | -| `GetSessionToken` | An IAM user key, optionally with MFA | 12 hours | -| `GetFederationToken` | An IAM user key | 12 hours | +| `GetSessionToken` | An IAM user key, optionally with MFA | 36 hours (default 12; root user 1 hour) | +| `GetFederationToken` | An IAM user key | 36 hours (default 12; root user 1 hour) | `DurationSeconds` on `AssumeRole` accepts 900 seconds upward, bounded by the role's `MaxSessionDuration`, which is itself settable between 1 and 12 hours. The default is diff --git a/docs/signing/04-variants.ja.md b/docs/signing/04-variants.ja.md index 22dda3f..167ee81 100644 --- a/docs/signing/04-variants.ja.md +++ b/docs/signing/04-variants.ja.md @@ -120,5 +120,5 @@ WebCrypto だけでは実装できない。公開鍵の導出には「自分で このリポジトリは `@noble/curves` を使っている。 1つ書いておく価値のある帰結。`@noble/curves` は RFC 6979 の決定的 nonce が既定なので、ここでは同じ -リクエストに2回署名すると同じバイト列になる。SDK の署名処理は一般に乱数の nonce を使うので、そうはならない (SDK ごとには未検証)。どちらも +リクエストに2回署名すると同じバイト列になる。これはこの実装の性質で、SigV4a の性質ではない。ECDSA は乱数の nonce も許すので、そういう署名処理なら毎回違うバイト列になり、それでも同じように検証は通る。どちらも 検証は通り、再現するのは一方だけ。SigV4a の署名に固定テストベクタを書こうとすると、ここが効いてくる。 diff --git a/docs/signing/04-variants.md b/docs/signing/04-variants.md index b9ac920..9e9ff06 100644 --- a/docs/signing/04-variants.md +++ b/docs/signing/04-variants.md @@ -127,7 +127,7 @@ point by a scalar you chose, and `SubtleCrypto` exposes no scalar multiplication curve arithmetic has to come from a library. This repository uses `@noble/curves`. One consequence worth stating: `@noble/curves` defaults to the RFC 6979 deterministic -nonce, so signing the same request twice here gives identical bytes. SDK signers typically -use a randomised nonce and will not (unverified per SDK). Both verify; only one is -reproducible, which matters if you ever try to write a fixed test vector for a SigV4a -signature. +nonce, so signing the same request twice here gives identical bytes. That is a property of +this implementation, not of SigV4a: ECDSA permits a random nonce, and a signer that uses +one produces different bytes that verify just as well. It matters if you ever try to write +a fixed test vector for a SigV4a signature. diff --git a/docs/signing/05-verification.ja.md b/docs/signing/05-verification.ja.md index d1a304e..f922086 100644 --- a/docs/signing/05-verification.ja.md +++ b/docs/signing/05-verification.ja.md @@ -66,7 +66,7 @@ Glacier の署名ページには2つ目の例、streaming の `Upload Archive` **SigV4a の署名。** 原理的に固定できない。ECDSA は乱数を使う。代わりに、署名が導出した公開鍵で検証 できることを assert している。これは AWS が実際に行う検証と同じ。(この実装は `@noble/curves` の既定に -より RFC 6979 で決定的になる。SDK 側は一般にそうではないが、SDK ごとには未検証。) +より RFC 6979 で決定的になる。別の署名処理は乱数の nonce を使うかもしれない。) ## レビューで見つかった誤り diff --git a/docs/signing/05-verification.md b/docs/signing/05-verification.md index 864267d..cc8e6d6 100644 --- a/docs/signing/05-verification.md +++ b/docs/signing/05-verification.md @@ -74,7 +74,7 @@ transcription slips; it does not rule out both having read the prose the same wr **SigV4a signatures.** Not pinnable in principle: ECDSA is randomised. What is asserted instead is that a signature verifies against the derived public key, which is the check AWS performs. (This implementation happens to be deterministic because `@noble/curves` -defaults to RFC 6979; SDK signers typically are not, though that is unverified per SDK.) +defaults to RFC 6979; another signer may use a random nonce.) ## Corrections found while reviewing diff --git a/docs/signing/README.ja.md b/docs/signing/README.ja.md index 83a016d..48e34eb 100644 --- a/docs/signing/README.ja.md +++ b/docs/signing/README.ja.md @@ -2,7 +2,7 @@ # ノート -このノートは[署名の章](https://0-draft.github.io/aws-credentials/?lang=ja#signing)の裏付けです。もとは `caller-identity` プロジェクト向けに書いたもので、2026-11-08 にこのリポジトリへ統合した際に移しました。 +このノートは[署名の章](https://0-draft.github.io/aws-credentials/?lang=ja#signing)の裏付け。もとは `caller-identity` プロジェクト向けに書いたもので、2026-11-08 にこのリポジトリへ統合した際に移した。 サイトがインタラクティブに見せている内容の、長い版。パネルに収まらない部分をここに置く。各仕組みが なぜその形なのか、ドキュメントと実装がどこで食い違うのか、そしてここに書いた主張をどう検証したか。 @@ -25,7 +25,7 @@ flowchart TD subgraph issue["クレデンシャルの出所"] iam["IAM{t({ - en: "Reproducible here because this implementation uses the RFC 6979 deterministic nonce. SDK signers typically use a randomised nonce, so the same request gives different bytes each time. Both verify; only one is reproducible.", - ja: "この実装は RFC 6979 の決定的 nonce を使うので、毎回同じ結果になります。SDK の署名処理は一般に乱数の nonce を使うので、同じリクエストでも毎回バイト列が変わります。どちらも検証は通り、再現できるのは片方だけです。", + en: "Reproducible here because this implementation uses the RFC 6979 deterministic nonce. A signer that uses a random nonce, which ECDSA allows, gives different bytes for the same request, and they verify just as well.", + ja: "この実装は RFC 6979 の決定的 nonce を使うので、毎回同じ結果になります。ECDSA は乱数の nonce も許すので、そういう署名処理なら同じリクエストでも毎回バイト列が変わり、それでも同じように検証が通ります。", })}
diff --git a/src/features/signing/sigv4a.test.ts b/src/features/signing/sigv4a.test.ts index 5b2c909..e1093bc 100644 --- a/src/features/signing/sigv4a.test.ts +++ b/src/features/signing/sigv4a.test.ts @@ -23,8 +23,7 @@ import { * The signature is a separate matter. ECDSA is randomised in general, so a * SigV4a signature is not something a vendor could publish as a fixed vector * anyway. @noble/curves happens to default to the deterministic RFC 6979 nonce, - * which makes ours reproducible, while SDK signers typically use a randomised - * nonce (unverified per SDK). What is portable across both is that the + * which makes ours reproducible; a signer using a random nonce would not be. What is portable across both is that the * signature verifies against the derived public key, which is the check AWS * actually performs. */ @@ -204,11 +203,9 @@ describe("signing", () => { const a = await signSigV4a(canonicalRequest, AWS_EXAMPLE, "host", options); const b = await signSigV4a(canonicalRequest, AWS_EXAMPLE, "host", options); - // Worth stating rather than assuming: ECDSA is randomised in general, and - // SDK signers typically use a randomised nonce, so the same request signed - // twice by an SDK is not expected to produce identical bytes. @noble's - // default is the deterministic RFC 6979 nonce, so ours does. Both verify; - // only one is reproducible. + // Worth stating rather than assuming: ECDSA permits a random nonce, and a + // signer using one would produce different bytes each time. @noble's + // default is the deterministic RFC 6979 nonce, so ours does not. expect(a.signature).toBe(b.signature); expect(verifySigV4a(a.signature, a.stringToSign, a.keyPair.publicKeyHex)).toBe(true); }); From 7c2228a81229ef2a73a15c1b8d56cce8eed028ab Mon Sep 17 00:00:00 2001 From: kanywst <45947799+kanywst@users.noreply.github.com> Date: Sun, 8 Nov 2026 11:37:06 +0900 Subject: [PATCH 5/5] docs(signing): state the replay window precisely and realign the JA variants note --- docs/signing/02-sigv4.ja.md | 3 ++- docs/signing/02-sigv4.md | 5 +++-- docs/signing/04-variants.ja.md | 5 +++-- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/docs/signing/02-sigv4.ja.md b/docs/signing/02-sigv4.ja.md index 305c096..32a4787 100644 --- a/docs/signing/02-sigv4.ja.md +++ b/docs/signing/02-sigv4.ja.md @@ -46,7 +46,8 @@ sequenceDiagram | `SecretAccessKey` | **絶対に乗らない** | HMAC の入力としてローカルで使うだけ | この非対称性が、署名と bearer token の違いそのもの。署名済みリクエストを傍受しても手に入るのは、 -既に使い終わったその1本だけ。bearer token を傍受すると、クレデンシャルそのものが手に入る。 +その1本だけで、再送できるのも時刻ずれの許容幅の中で、同じメソッド・パス・ボディのままに限られる。 +bearer token を傍受すると、クレデンシャルそのものが手に入る。 ## canonical request diff --git a/docs/signing/02-sigv4.md b/docs/signing/02-sigv4.md index abb7e94..be25f8b 100644 --- a/docs/signing/02-sigv4.md +++ b/docs/signing/02-sigv4.md @@ -47,8 +47,9 @@ Of the three components of a temporary credential, two travel and one does not. | `SecretAccessKey` | **Never** | Used locally as HMAC input only | That asymmetry is the difference between a signature and a bearer token. Intercepting a -signed request gives you that one request, already spent. Intercepting a bearer token -gives you the credential. +signed request gives you that one request, replayable only inside the clock-skew window +and only with the same method, path and body. Intercepting a bearer token gives you the +credential. ## The canonical request diff --git a/docs/signing/04-variants.ja.md b/docs/signing/04-variants.ja.md index 167ee81..7e7f9dc 100644 --- a/docs/signing/04-variants.ja.md +++ b/docs/signing/04-variants.ja.md @@ -120,5 +120,6 @@ WebCrypto だけでは実装できない。公開鍵の導出には「自分で このリポジトリは `@noble/curves` を使っている。 1つ書いておく価値のある帰結。`@noble/curves` は RFC 6979 の決定的 nonce が既定なので、ここでは同じ -リクエストに2回署名すると同じバイト列になる。これはこの実装の性質で、SigV4a の性質ではない。ECDSA は乱数の nonce も許すので、そういう署名処理なら毎回違うバイト列になり、それでも同じように検証は通る。どちらも -検証は通り、再現するのは一方だけ。SigV4a の署名に固定テストベクタを書こうとすると、ここが効いてくる。 +リクエストに2回署名すると同じバイト列になる。これはこの実装の性質で、SigV4a の性質ではない。ECDSA +は乱数の nonce も許すので、そういう署名処理なら毎回違うバイト列になり、それでも同じように検証は通る。 +SigV4a の署名に固定テストベクタを書こうとすると、ここが効いてくる。