kms

KMS

Parity grade: A · SDK aws-sdk-go-v2/service/kms@v1.59.0 · last audited 2026-07-23 (13c27883a00454a6e63bc767d096528ecfd6c4b1)

Coverage

Known gaps

• RESOLVED 2026-07-23: GrantConstraints had no SourceArn field (real SDK: GrantConstraints.SourceArn). Added; round-trips through CreateGrant -> ListGrants/ListRetirableGrants/Snapshot-Restore. NOT enforced -- no operation in this mock threads a caller/resource ARN through crypto calls to check against it, and no other service adapter currently supplies one either; enforcement remains cross-cutting request-context plumbing, not a KMS-local fix (bd: gopherstack-w3k, still open for the enforcement half only).
• RESOLVED 2026-07-23: CreateGrantInput had no GrantTokens field (real SDK: authorizes the CreateGrant call itself via an existing not-yet-consistent grant). Added; accepted as a no-op (no IAM/authorization layer exists anywhere in this mock to authorize against), same precedent as CreateKeyInput/ReplicateKeyInput's BypassPolicyLockoutSafetyCheck.
• RESOLVED 2026-07-23: GranteeServicePrincipal / RetiringServicePrincipal (AWS-service grantees) were not modeled on CreateGrantInput. Added, WITH real validation (exactly one of GranteePrincipal/GranteeServicePrincipal; RetiringPrincipal/RetiringServicePrincipal mutually exclusive; a service grantee requires a SourceArn constraint + a retiring principal), matching the real CreateGrantInput doc comments. No AWS-service-principal simulation exists (still no IAM layer), but the wire shape and its documented validation rules are both real and enforced now, unlike SourceArn's constraint-enforcement half above which has nothing local to check against.
• RESOLVED 2026-07-12: DescribeKeyInput was missing the GrantTokens field -- added + wired validateGrantTokenPresence (see the DescribeKey op row and describe_key_grant_tokens_test.go). Unlike the CreateGrant/CreateGrantInput GrantTokens gap above (which authorizes the CreateGrant call itself and has nothing to validate without an IAM layer), DescribeKey's GrantTokens resolve to real existing grants, so validation is meaningful and AWS-accurate here (DescribeKey declares InvalidGrantTokenException).
• RESOLVED 2026-07-12: the region-scoped KeyId resolution inconsistency (GetKeyPolicy/PutKeyPolicy/CreateGrant/ListGrants/RevokeGrant/RetireGrant indexed their policiesStore/grantsRegion using the request region instead of an ARN's embedded region). Root cause was two-fold and both fixed at source: (1) these ops discarded the region resolveKeyID returned and re-used getRegion(ctx) -- fixed by adding a shared resolveKeyAndRegion helper (lookupKey now delegates to it too) that returns the key's actual region, and routing all six ops through it; (2) resolveKeyID's resolution cache stored only the resolved UUID and returned the REQUEST region on every cache hit, so even the region resolveKeyID returned was wrong for any ARN resolved more than once -- fixed by caching a {keyID, region} pair (region="" sentinel for aliases means 'derive from request context', so alias behavior is unchanged; ARN caches its own embedded region, which is safe because the region is part of the ARN cache key). Verified by region_scoped_resolution_test.go (cross-region ReplicateKey -> replica-ARN Put/GetKeyPolicy round-trip + full grant lifecycle by ARN, all while ctx defaults to the primary's region).
• RESOLVED 2026-09-07 (gopherstack-e76y): CreateKeyInput/KeyMetadata gained CustomKeyStoreID (real SDK: aws-sdk-go-v2/service/kms@v1.55.4 api_op_CreateKey.go:228, types/types.go:439). CreateKeyInput.CustomKeyStoreId's own doc comment (quoted in full): 'Creates the KMS key in the specified custom key store. The ConnectionState of the custom key store must be CONNECTED. To find the CustomKeyStoreID and ConnectionState use the DescribeCustomKeyStores operation. This parameter is valid only for symmetric encryption KMS keys in a single Region. You cannot create any other type of KMS key in a custom key store. When you create a KMS key in an CloudHSM key store, KMS generates a non-exportable 256-bit symmetric key in its associated CloudHSM cluster and associates it with the KMS key. When you create a KMS key in an external key store, you must use the XksKeyId parameter to specify an external key that serves as key material for the KMS key.' Implemented exactly what it states, no more: (1) the store must exist (CustomKeyStoreNotFoundException, extraction-confirmed in deserializeOpErrorCreateKey's error list); (2) its ConnectionState must be CONNECTED (CustomKeyStoreInvalidStateException, also extraction-confirmed, and its own doc comment names 'You requested the CreateKey operation in a custom key store that is not connected' as one of its own reasons for existing); (3) 'valid only for symmetric encryption KMS keys in a single Region' -- resolved KeySpec must be SYMMETRIC_DEFAULT, KeyUsage must be ENCRYPT_DECRYPT, and MultiRegion must be false, or the request is rejected with UnsupportedOperationException (ErrUnsupportedParameter, same sentinel already used elsewhere in this file for 'a specified parameter is not supported'). Declined only the external-key-store half: rather than accept a CustomKeyStoreId for an EXTERNAL_KEY_STORE-type store and silently ignore the doc's 'you must use the XksKeyId parameter' requirement, CreateKey rejects it outright (also UnsupportedOperationException) since XksKeyId itself is unmodeled -- see the new XksKeyId gap entry below (gopherstack-ufvn). The association persists on Key.CustomKeyStoreID and round-trips through DescribeKey.
• OPEN 2026-09-08 (gopherstack-ufvn, follow-up to gopherstack-e76y; supersedes a same-day RESOLVED/OPEN split entry that was reverted): XksKeyId (external-key-store variant of the CustomKeyStoreId linkage, CreateKeyInput field, api_op_CreateKey.go:481-483) remains entirely unmodeled -- no field, no per-store external-key uniqueness tracking, none of XksKeyNotFoundException/XksKeyAlreadyInUseException/XksKeyInvalidConfigurationException (all three appear in CreateKey's own error list). A same-day pass added CreateKeyInput.XksKeyId plus validateXksKeyID (conditional-required-when-Origin=EXTERNAL_KEY_STORE, plus XksKeyIdType's length/pattern constraints from botocore's service-2.json), raising ErrValidation on failure -- then reverted it, because ErrValidation's wire code, ValidationException, is not in CreateKey's declared error set (CloudHsmClusterInvalidConfiguration, CustomKeyStoreInvalidState, CustomKeyStoreNotFound, DependencyTimeout, InvalidArn, KMSInternal, LimitExceeded, MalformedPolicyDocument, Tag, UnsupportedOperation, XksKeyAlreadyInUse, XksKeyInvalidConfiguration, XksKeyNotFound -- confirmed against kms@v1.59.0 deserializeOpErrorCreateKey), and this service models no ValidationException type at all (zero matches for 'type ValidationException struct' anywhere in the vendored kms module's types package). A caller using a typed client can never match an undeclared code; it degrades to a generic smithy error. Worse, validateXksKeyID ran before the existing CustomKeyStoreId linkage check, so for Origin=EXTERNAL_KEY_STORE with a missing or malformed XksKeyId, callers got this unmatchable code instead of the declared, matchable UnsupportedOperationException they got before the field existed -- a regression, not an improvement, since gopherstack declines the external-key-store linkage entirely regardless of XksKeyId's own shape. No declared code was found that fits a malformed/missing XksKeyId string: XksKeyInvalidConfigurationException's own doc is about the external key's own configuration ('The external key must be an AES-256 symmetric key that is enabled and performs encryption and decryption'), not about the identifier string being absent or badly formed, and XksKeyNotFoundException/XksKeyAlreadyInUseException require actually resolving against an external key manager, which doesn't exist here. CreateKey therefore still rejects any attempt to create a key in an EXTERNAL_KEY_STORE-type custom key store with UnsupportedOperationException, pinned by TestCreateKey_CustomKeyStore_Rejections's "external key store type" subtest (custom_key_store_link_test.go, sentinel-level) and TestCreateKey_ExternalKeyStore_UnsupportedOperationException_RealClient (wire_field_fixes_test.go, errors.As against the real *types.UnsupportedOperationException). Deliberate scope decision, not an oversight -- implementing the linkage is a real feature (see gopherstack-ufvn), not a bug fix, and no wire-shape-only validation of XksKeyId is worth adding without a declared error code to carry it.
• RESOLVED 2026-09-07 (gopherstack-o3rp): confirmed and fixed. DisconnectCustomKeyStore's own doc comment (kms@v1.55.4 api_op_DisconnectCustomKeyStore.go, quoted in full): 'While a custom key store is disconnected, all attempts to create KMS keys in the custom key store or to use existing KMS keys in [cryptographic operations] will fail.' Error choice was NOT CustomKeyStoreInvalidStateException (that type's own doc enumerates only CreateKey/ConnectCustomKeyStore/DisconnectCustomKeyStore/UpdateCustomKeyStore/DeleteCustomKeyStore/GenerateRandom preconditions -- no crypto op) but KMSInvalidStateException, whose own doc says explicitly: 'For cryptographic operations on KMS keys in custom key stores, this exception represents a general failure with many possible causes.' Extraction of all twelve crypto ops' deserializeOpError functions (Encrypt, Decrypt, ReEncrypt, GenerateDataKey/WithoutPlaintext/Pair/PairWithoutPlaintext, Sign, Verify, GetPublicKey, GenerateMac, VerifyMac, DeriveSharedSecret -- kms@v1.55.4 deserializers.go) confirms every one declares KMSInvalidStateException and none declares CustomKeyStoreInvalidStateException, so the existing ErrKeyInvalidState sentinel (already mapped in kmsErrorTable, no new row needed) was reused rather than adding a new one. Confirmed DisconnectCustomKeyStore itself is unguarded against live keys (only DeleteCustomKeyStore refuses while keys reference the store), so the disconnected-with-live-keys case this issue depends on is reachable. Fix: all twelve crypto ops fetch key material through one shared helper, requireKeyMaterial(region, key) in store.go -- confirmed by grep before touching anything, not assumed -- so the guard was added there once (check Key.CustomKeyStoreID's backing store ConnectionState before returning material) rather than duplicated at each of the twelve call sites; those call sites only changed to pass the already-in-scope *Key instead of a bare keyID string. Regression test TestEncrypt_DisconnectedCustomKeyStore_WireErrorType drives the full HTTP handler (create+connect a store, create a key in it, disconnect, Encrypt) and asserts the JSON Type field is KMSInvalidStateException; confirmed pre-fix by neutering the new guard block in requireKeyMaterial, which makes the test fail with 200 OK instead of 400/KMSInvalidStateException.
• RESOLVED 2026-09-07 (gopherstack-akm2): confirmed. ConnectCustomKeyStore/DisconnectCustomKeyStore/DeleteCustomKeyStore's own pre-existing state-transition guards (custom_key_stores.go) all returned ErrKeyInvalidState (KMSInvalidStateException), but raw error extraction of all four ops' deserializeOpError functions (kms@v1.55.4 deserializers.go) shows CustomKeyStoreInvalidStateException declared and KMSInvalidStateException declared by NONE of them -- confirmed by types/errors.go's CustomKeyStoreInvalidStateException doc comment, which lists exactly ConnectCustomKeyStore/DisconnectCustomKeyStore/UpdateCustomKeyStore/DeleteCustomKeyStore's non-connected/non-disconnected preconditions as its own reasons for existing. Fixed: all three call sites now use the existing ErrCustomKeyStoreInvalidState sentinel (added by gopherstack-e76y for CreateKey's check, previously unused by these three pre-existing guards). Also fixed a second, dependent gap this exposed: ErrCustomKeyStoreInvalidState was itself absent from handler.go's kmsErrorTable, so even CreateKey's existing use of it fell through to the generic 500 KMSInternalException default instead of the real 400 CustomKeyStoreInvalidStateException -- added the missing table entry (both CustomKeyStoreInvalidStateException and KMSInvalidStateException are ErrorFault: Client in the real SDK, so the HTTP status stays 400 either way; only the JSON error Type field was wrong). UpdateCustomKeyStore is NOT touched by this fix -- it has no ConnectionState guard at all in this backend (a separate, pre-existing feature gap, not a wrong-code bug; not added here to stay in scope). ErrCustomKeyStoreHasKeys (DeleteCustomKeyStore's separate 'store still has keys' check) is also absent from kmsErrorTable, same failure mode as the CreateKey gap above -- left unfixed, out of this issue's scope, noted for a future pass.
• RESOLVED 2026-09-07 (gopherstack-ylkc): the ErrCustomKeyStoreHasKeys gap flagged (but left unfixed) by gopherstack-akm2 above. DeleteCustomKeyStore's still-has-keys guard (custom_key_stores.go) returns ErrCustomKeyStoreHasKeys (CustomKeyStoreHasCMKsException, added by gopherstack-e76y) but had no row in handler.go's kmsErrorTable, so it fell through the linear errors.Is scan to the generic 500 KMSInternalException default instead of the real 400 CustomKeyStoreHasCMKsException. Extraction of deserializeOpErrorDeleteCustomKeyStore (kms@v1.55.4 deserializers.go) confirms the op declares it: UnknownError, CustomKeyStoreHasCMKsException, CustomKeyStoreInvalidStateException, CustomKeyStoreNotFoundException, KMSInternalException. types/errors.go confirms CustomKeyStoreHasCMKsException.ErrorFault() is smithy.FaultClient, so the fix is a 400, not the pre-fix 500. Fixed: added the missing table row. A full sweep of every sentinel in errors.go against kmsErrorTable (comm -23 on both lists) found exactly this one omission and no others -- the akm2 CustomKeyStoreInvalidState gap it fixed earlier this session was the only sibling, and is already resolved above. Regression test TestDeleteCustomKeyStore_HasKeys_WireErrorType drives the full HTTP handler and asserts the JSON Type field (not just ErrorIs on the sentinel -- an ErrorIs-only assertion is exactly how both this gap and the akm2 one went undetected: TestDeleteCustomKeyStore_WithLinkedKey_Rejected in custom_key_store_link_test.go calls the backend directly and asserts only require.Error + assert.ErrorIs, which passes identically whether or not the table row exists). Confirmed pre-fix: reverting the table row makes the new test fail with 500/KMSInternalException instead of 400/CustomKeyStoreHasCMKsException.
• RESOLVED 2026-09-07 (gopherstack-8u3f): cmd/errtargetaudit's data-table-aware pass (gopherstack-yn2o) resolved 41/54 kms ops and reported 15 class A findings -- a wire code emitted on an op whose deserializeOpError does not declare it. Every finding individually re-extracted against the pinned kms@v1.55.4 deserializers.go (not trusted from the tool summary). Verdicts: CONFIRMED and FIXED (4 root causes, 5 findings): (1) CancelKeyDeletion emitted DisabledException for a merely-Disabled key -- its own guard (KeyState != PendingDeletion && != PendingReplicaDeletion) is entirely about 'not pending deletion', unrelated to Disabled-vs-other, but it called the shared keyStateError(key) helper (Disabled->DisabledException, else->KMSInvalidStateException) instead of unconditionally raising KMSInvalidStateException as its own doc comment already said it should; keys.go:490-492 now raises ErrKeyInvalidState directly. (2) ImportKeyMaterial's wrong-state guard (KeyState != PendingImport) had the identical bug for the identical reason -- import.go:191-193 now also raises ErrKeyInvalidState directly instead of keyStateError(key). Neither CancelKeyDeletion nor ImportKeyMaterial declares DisabledException in kms@v1.55.4; both declare KMSInvalidStateException. keyStateError() itself is untouched -- callers that legitimately reach it with Disabled reachable (Decrypt/Encrypt/CreateGrant/DisableKeyRotation/EnableKeyRotation etc., all of which DO declare DisabledException) are unaffected, proven by TestDecrypt_DisabledKey_StillDisabledException. (3) VerifyMac's HMAC-mismatch branch (hmac.go) reused ErrInvalidSignature ('KMSInvalidSignatureException', the sentinel Verify's asymmetric-signature mismatch legitimately uses -- confirmed still correct via the pre-existing TestKMSHandlerInvalidSignatureError) instead of its own declared code. VerifyMac's deserializeOpError recognizes KMSInvalidMacException, a distinct type Verify does not declare. Added a new sentinel ErrInvalidMac ('KMSInvalidMacException', errors.go) + kmsErrorTable row (handler.go) and switched the hmac.go call site to it. (4) checkKeyMaterialExpiry (store.go), called only by Encrypt and Decrypt, raised ErrExpiredKeyMaterial ('ExpiredImportTokenException') when an EXTERNAL key's imported material had passed ValidTo -- neither Encrypt nor Decrypt declares ExpiredImportTokenException (only ImportKeyMaterial does, and nothing in this codebase currently reaches it that way); both declare KMSInvalidStateException, matching real AWS's behavior of transitioning an expired-material key back toward PendingImport. Switched to ErrKeyInvalidState. This exposed a genuinely hollow pre-existing test (TestKMS_ErrorClassification_MissingTableEntries/expired_import_material in handler_replication_maintenance_test.go) that drove the full HTTP handler but asserted the wrong wire Type; corrected to KMSInvalidStateException, plus two more backend-level errors.Is hollow tests found the same way while running the suite (TestKMSCancelKeyDeletion_RequiresPendingDeletion/disabled_key_fails in keys_test.go, TestVerifyMac_WrongMac in hmac_test.go) -- both asserted the pre-fix wrong sentinel and were corrected in place. CONFIRMED, LEFT FOR JUDGMENT CALL (2 findings): CreateKey's validateKeySpecUsage (keys.go) rejects an incompatible KeySpec/KeyUsage pair with ErrInvalidKeyUsage ('InvalidKeyUsageException'), which CreateKey's deserializeOpError does not declare (CreateKey declares no key-usage-shaped error at all). ValidationException is the closest real candidate, matching this file's established precedent for undeclared-per-op constraint checks (errors.go's ErrValidation comment, gopherstack-e3yu), but not re-verified against a live smithy trait for this specific field pair, so left for confirmation rather than assumed. DescribeKey's InvalidGrantTokenException (keys.go:277, validateGrantTokenPresence) is a harder case: extraction of deserializeOpErrorDescribeKey in the PINNED kms@v1.55.4 shows only DependencyTimeoutException/InvalidArnException/KMSInternalException/NotFoundException/UnknownError -- no InvalidGrantTokenException -- which directly contradicts this file's own prior 'RESOLVED 2026-07-12' gap entry above (citing kms@v1.54.0 and claiming DescribeKey does declare it). Re-extraction re-run twice against the exact function boundary to rule out a copy error; the pinned-version result stands. Left unfixed rather than unilaterally reverted because the existing validateGrantTokenPresence call, its dedicated describe_key_grant_tokens_test.go, and the above gap entry were a deliberate prior feature addition with its own reasoning, not an oversight -- reversing it removes real (if AWS-inaccurate per this SDK pin) grant-token validation and needs a human call on whether the 1.54.0->1.55.4 discrepancy is a real SDK model change or the earlier session verified against the wrong artifact. ImportKeyMaterial's InvalidKeyUsageException (import.go, 4 sentinel sites all reusing ErrInvalidKeyUsage: line ~156 RSA-OAEP unwrap failure, ~198 KeySpec!=symmetric, ~204 empty KeyMaterial, ~213 wrong-length material) is CONFIRMED not declared (ImportKeyMaterial's error list has no InvalidKeyUsageException) but needs a 4-way judgment call, not a single substitution: the unwrap-failure site plausibly maps to InvalidCiphertextException or IncorrectKeyMaterialException (both declared), the KeySpec-mismatch site to UnsupportedOperationException (declared, matches this mock's own doc comment about only supporting SYMMETRIC_DEFAULT), the empty-material site plausibly to ValidationException (smithy required-field precedent) or IncorrectKeyMaterialException, and the wrong-length site most plausibly to IncorrectKeyMaterialException. Left for a follow-up issue rather than guessed. FALSE POSITIVES (7 findings, all confirmed unreachable by direct code reading, not by trusting the tool): DisableKey and EnableKey's own keyStateError(key) calls (keys.go) are only reached when KeyState is PendingDeletion/PendingImport/PendingReplicaDeletion (the guard explicitly excludes Disabled before calling it), so keyStateError always returns ErrKeyInvalidState there -- DisabledException is statically unreachable through these two call sites, contra the tool's one-hop-callee approximation. ScheduleKeyDeletion's keyStateError(key) call (keys.go) is guarded identically (KeyState == PendingDeletion only), same conclusion. ListResourceTags/TagResource/UntagResource (handler_tags.go) all delegate key-existence checking to h.Backend.DescribeKey(ctx, &DescribeKeyInput{KeyID: input.KeyID}) with GrantTokens left at its zero value, so even though there IS a real call path from these ops down into validateGrantTokenPresence (which is where the tool's constructor-classifier evidence comes from), the argument reaching it is always an empty slice, which validateGrantTokenPresence special-cases to an immediate nil return -- InvalidGrantTokenException is unreachable via this path regardless of the DescribeKey finding above. ReplicateKey (replication.go) has no call path to validateGrantTokenPresence at all -- it does not call DescribeKey and does not accept/forward GrantTokens anywhere in its own body; this appears to be a spurious attribution with no supporting call-graph edge, not even the empty-argument case the tagging ops have. Gates: go test -race -count=1 ./services/kms/... and golangci-lint run services/kms/... both green. Every changed production line neutered individually (reverted -> confirmed compiles -> confirmed a specific test fails -> restored) before reporting; see the issue's chat transcript for the per-line table.
• RESOLVED 2026-09-07 (gopherstack-h88p): the ImportKeyMaterial half of gopherstack-8u3f's 'LEFT FOR JUDGMENT CALL' finding above, decided per site (raw extraction re-run, both operations): ImportKeyMaterial declares DependencyTimeoutException/ExpiredImportTokenException/IncorrectKeyMaterialException/InvalidArnException/InvalidCiphertextException/InvalidImportTokenException/KMSInternalException/KMSInvalidStateException/NotFoundException/UnsupportedOperationException -- no InvalidKeyUsageException, no ValidationException. Four sites: (1) resolveKeyMaterial's RSA-OAEP unwrap failure (import.go) -> ErrInvalidCiphertext (InvalidCiphertextException); its own doc comment is explicit for exactly this op: 'From the ImportKeyMaterial operation, the request was rejected because KMS could not decrypt the encrypted (wrapped) key material.' (2) The KeySpec!=SYMMETRIC_DEFAULT guard -> ErrUnsupportedParameter (UnsupportedOperationException, already used elsewhere in this file for KeySpec-shaped mismatches); UnsupportedOperationException's own doc covers 'a specified parameter is not supported or a specified resource is not valid for this operation' -- the key's own KeySpec is the resource here, not a request parameter, but the doc's second clause fits. (3) Empty-KeyMaterial guard -> ErrIncorrectKeyMaterial (IncorrectKeyMaterialException), same sentinel as (4). First pass swapped this site to ErrValidation on the reasoning that EncryptedKeyMaterial is a required field a real SDK client rejects before the wire, 'same as GenerateMac's MacAlgorithm-empty check' -- caught in review as swapping one undeclared code (InvalidKeyUsageException) for another undeclared one (ValidationException, confirmed absent from every deserializer in the whole kms@v1.55.4 module, not just this op), with 'we already do this elsewhere' doing the load-bearing work instead of an actual declared-set fit. Corrected: IncorrectKeyMaterialException's own doc disjunction -- 'is, expired, invalid, or does not meet expectations' -- covers empty material under 'invalid', the same declared code the wrong-length site below uses under 'does not meet expectations'; AWS's own doc groups both failure modes under one exception, so one sentinel serving both sites matches the SDK's own granularity rather than losing a real distinction. (4) Wrong-length guard -> new sentinel ErrIncorrectKeyMaterial (IncorrectKeyMaterialException, errors.go + kmsErrorTable row added); its doc fits precisely: 'the key material in the request is, expired, invalid, or does not meet expectations.' CreateKey's half of the same 8u3f finding was NOT touched: re-extraction confirms CreateKey's declared set (CloudHsmClusterInvalidConfigurationException/CustomKeyStore{InvalidState,NotFound}Exception/DependencyTimeoutException/InvalidArnException/KMSInternalException/LimitExceededException/MalformedPolicyDocumentException/TagException/UnsupportedOperationException/XksKey{AlreadyInUse,InvalidConfiguration,NotFound}Exception) has no key-usage-shaped code and, unlike 8u3f's assumption, does NOT include ValidationException (confirmed absent from the whole kms@v1.55.4 SDK module, not just this op) -- so validateKeySpecUsage's ErrInvalidKeyUsage site and the HMAC+MultiRegion ErrInvalidKeyUsage site (both keys.go, both inside CreateKey) are a third bug shape (no declared code fits at all, unlike a two-candidate ambiguity) and are left as a documented landmine rather than swapped to a guess; filed as a fresh follow-up rather than left silently. Verified no pre-existing test asserted the wrong wire code for any of the four ImportKeyMaterial sites (searched all *_test.go for InvalidKeyUsageException; the only hits were Encrypt/VerifyMac/key_agreement, all legitimate), so 0 pre-existing tests needed correction. New regression tests in import_error_wiring_test.go drive the full HTTP handler and assert the JSON Type field for all four sites, plus two guard tests (Decrypt, VerifyMac) proving ops that legitimately declare InvalidKeyUsageException still emit it. Every changed production line neutered individually (reverted -> confirmed compiles -> confirmed the matching test fails with the specific pre-fix wire type -> restored), including the new kmsErrorTable row (reverting it alone drops the wrong-length case to 500/KMSInternalException). Gates: go test -race -count=1 ./services/kms/... and golangci-lint run services/kms/... both green. SIZING NOTE, not fixed here (out of scope for this issue): ErrValidation (ValidationException) itself remains a live sentinel with 36 raise sites across 16 non-test files (aliases.go, crypto.go x4, custom_key_stores.go x2, encryption.go, grants.go x7, handler_grants_policies.go, hmac.go x2 [including the GenerateMac MacAlgorithm-empty precedent this issue's first pass leaned on], import.go x3 [ExpirationModel validation + an internal type-assertion guard; the two former InvalidKeyUsageException sites this issue fixed no longer use it], keys.go x4, key_agreement.go x2, key_policies.go, random.go, replication.go x2, rotation.go, signing.go x2, store.go), every one of them emitting a code confirmed absent from every operation's deserializeOpError in the whole kms@v1.55.4 module (not just the op each site reaches). A future pass should re-run the per-site judgment call this issue applied to CreateKey and ImportKeyMaterial across all 36: for each, either find a real declared code (per-op, per-site, not by pattern-matching a sibling site) or leave a landmine -- 'the sentinel already exists elsewhere' is not itself a fit.
• RESOLVED 2026-09-07 (gopherstack-i4q8): the h88p sizing note's full 36-site sweep. Re-derived the inventory from scratch rather than trusting h88p's per-file count (grep -n ErrValidation across the 16 non-test files, minus definition/comment hits in errors.go/handler.go/store.go/keys.go) -- got 36 total but grants.go is 8 sites, not 7 (h88p's list missed ListRetirableGrants' RetiringPrincipal/RetiringServicePrincipal exclusivity check, grants.go ~line 433; validateGrantPrincipals' 4 sites + CreateGrant's own 3 + that one = 8), so the file-count discrepancy cancels out to the same 36. For every site: traced its reaching operation(s) by grep on the enclosing function's callers (not assumed from the file it lives in), extracted that op's declared set with awk '/deserializeOpError<Op>\\(/,/^}/' deserializers.go | grep -oE '"[A-Za-z0-9]+"', and read the doc comment of any plausible candidate before accepting or rejecting it. FIXED (4 sites, all reused existing sentinels -- no new ones needed): CreateKey's Description-length check (keys.go, validateCreateKeyLimits) and CreateGrant's Name-length check (grants.go, inside CreateGrant) both -> ErrLimitExceeded (LimitExceededException); its own doc is explicit -- 'The request was rejected because a length constraint or quota was exceeded' -- and both ops declare it (CreateKey already reuses it for its Tags-count check one line below the Description one; CreateGrant declares it for grant-count-per-key, already used lower in the same function). PutKeyPolicy's PolicyName!='default' check, at BOTH of its two sites (handler_grants_policies.go's dispatch-level check, which is what a real client actually hits, and key_policies.go's own backend-level copy of the identical check) -> ErrUnsupportedParameter (UnsupportedOperationException); its doc -- 'a specified parameter is not supported' -- matches PolicyName's own field doc in api_op_PutKeyPolicy.go ('The only valid value is default'), the same enum-of-one pattern ErrUnsupportedParameter already covers for KeySpec/KeyPairSpec elsewhere, and PutKeyPolicy declares the code. The key_policies.go copy is provably dead code in production -- grep confirms Backend.PutKeyPolicy has exactly one caller (the handler dispatch), which already normalizes/rejects PolicyName before calling it -- fixed anyway as defense in depth and because it is reachable directly in tests (see key_policies_test.go). LEFT, 32 sites, each with an inline landmine comment naming the operation's declared set and why nothing in it fits (see aliases.go:203ish, crypto.go x4, custom_key_stores.go x2, encryption.go:43ish, grants.go x7 [4 in validateGrantPrincipals + the Operations-empty and invalid-grant-operation checks + ListRetirableGrants], hmac.go x2, import.go x3, keys.go x2 [UpdateKeyDescription's Description-length check does NOT get CreateKey's fix -- UpdateKeyDescription's declared set has no length/quota code at all -- and ListKeys' Limit check], key_agreement.go x2, random.go, replication.go x2, rotation.go, signing.go x2, store.go). Two are shared helpers reached by ops with DIFFERING declared sets, called out separately per this issue's instructions rather than folded into the per-site list: validateEncryptionContextSize (crypto.go) is reached by GenerateDataKey(WithoutPlaintext), GenerateDataKeyPair(WithoutPlaintext), Encrypt, Decrypt and ReEncrypt -- traced via grep on the helper's own name plus validateGenerateDataKeyInput/validateReEncryptInput's callers -- but the outcome is the same either way (none of the 7 declared sets has an EncryptionContext-size code, so the multi-op reachability doesn't change the verdict, just widens who it's wrong for); resolveKeyID (store.go) is reached by nearly every KeyId-resolving op (each with its own declared set per the pre-existing qxaj comment on the same function) but the specific branch is cache corruption, not a real client-triggerable condition, so there is no per-op fit question to answer at all. Two more are internal defensive checks unreachable by any request (import.go's wrapping-key type assertion, store.go's cache-entry type assertion) -- noted as a fourth, distinct sub-category (not a wrong-code bug at all; there is no real per-op question to resolve). Regression tests (handler_keys_test.go, handler_grants_policies_test.go) drive the full HTTP handler and assert the JSON Type field plus 'not ValidationException' plus a no-mutation check (rejected CreateKey creates no key, rejected CreateGrant creates no grant, rejected PutKeyPolicy leaves the stored policy unchanged) for all 4 fixed sites; the pre-existing TestKeyPolicy_InvalidPolicyName (key_policies_test.go), which called the backend directly and only asserted require.Error, was strengthened to assert.ErrorIs the correct sentinel and assert.NotErrorIs ErrValidation -- proven necessary by neutering key_policies.go's fix alone with the OLD assertion in place (full suite green, because require.Error is blind to which error), then again with the STRENGTHENED assertion (fails at key_policies_test.go:57-58 with the exact predicted 'expected UnsupportedOperationException, found ValidationException' diff). All 4 production lines individually neutered (reverted -> go build succeeded -> the matching test failed at the exact predicted line/diff -> restored): keys.go:145, grants.go:106, handler_grants_policies.go:67 (each caught by its new test), key_policies.go:28 (caught only by the strengthened pre-existing test, not by any handler test, since the line is unreachable via HTTP). Gates: go test -race -count=1 ./services/kms/... and golangci-lint run services/kms/... both green. Filed as follow-up, not fixed here: the third-bug-shape sites among the 32 left (CreateGrant's invalid-Operations-entry check, structurally identical to CreateKey's own undeclared KeyUsage-mismatch gap noted in h88p's entry above, both 5rjn-class) and the two conflicting-declared-set shared helpers, as candidates for either a future declared-code discovery or a permanent landmine, per this issue's own scope boundary of fixing only what clearly fits.
• RESOLVED 2026-09-07 (gopherstack-yatn, orphan-code class): validateMacAlgorithm (crypto.go, reached by GenerateMac and VerifyMac) raised ErrInvalidAlgorithm ('InvalidAlgorithmException'), a code confirmed absent from the ENTIRE pinned kms@v1.55.4 module -- grep -rn InvalidAlgorithmException over the whole module returns nothing, not just 'wrong op'. Both GenerateMac's and VerifyMac's own deserializeOpError declare InvalidKeyUsageException, whose doc (types/errors.go:753-767) is explicit: 'the encryption algorithm or signing algorithm specified for the operation is incompatible with the type of key material in the KMS key (KeySpec)... For generating and verifying message authentication codes (MACs), the KeyUsage must be GENERATE_VERIFY_MAC.' Switched the call site to the pre-existing ErrInvalidKeyUsage sentinel (already in kmsErrorTable, no new row needed) and removed the now-dead ErrInvalidAlgorithm sentinel and its table row. Three pre-existing hmac_test.go assertions (TestGenerateMac_WrongAlgorithm_HMAC256KeyWithSHA512, TestGenerateMac_WrongAlgorithm_HMAC512KeyWithSHA256, TestVerifyMac_WrongAlgorithm) asserted the wrong wire string and were corrected in place. New regression tests (mac_algorithm_wiring_test.go) drive the full HTTP handler for both ops and assert the JSON Type field is InvalidKeyUsageException; confirmed failing pre-fix with the exact wrong value 'InvalidAlgorithmException'. Not authorization/enforcement-related -- pure algorithm-vs-keyspec validation, no grant/policy path touched. Gates: go test -race ./services/kms/... and golangci-lint run ./services/kms/... both green.
• RESOLVED 2026-09-07 (gopherstack-5rjn): CreateKey's two h88p/i4q8-left landmines (validateKeySpecUsage's call, keys.go, and the HMAC+MultiRegion check next to it) turned out to need two different fixes, not one. (1) validateKeySpecUsage's ErrInvalidKeyUsage raise was swapped to ErrUnsupportedParameter (UnsupportedOperationException): CreateKey's declared set (re-derived, matches h88p's list exactly, confirmed word-for-word against the live AWS API_CreateKey.html Errors section) has no key-usage-shaped code, and InvalidKeyUsageException's own doc (docs-2.json) is about an existing key's KeyUsage being wrong for the operation invoked, not this creation-time KeySpec/KeyUsage pairing -- a different condition, not just an undeclared one. UnsupportedOperationException is both declared by CreateKey and evidenced live for a KeySpec-shaped CreateKey rejection (developerguide hmac-create-key.html: an HMAC KeySpec unsupported in a Region -> UnsupportedOperationException), and its doc's first clause ('a specified parameter is not supported') covers a KeyUsage value unsupported for the given KeySpec. Weighed gopherstack-q9bs's ValidationException finding and declined it here: q9bs's evidence (GetPublicKey's malformed-DER-blob case) is a pre-dispatch, structural fault; a KeySpec/KeyUsage pairing is cross-field operation logic, a materially different condition, so ValidationException does not fit better than the existing UnsupportedOperationException precedent already used for the same shape (import.go's KeySpec!=SYMMETRIC_DEFAULT guard, gopherstack-h88p). (2) The HMAC+MultiRegion check was not a wrong-error-code bug at all -- its premise was false. kms@v1.55.4's own api_op_CreateKey.go doc comment (the pinned SDK source this whole campaign treats as ground truth) is explicit: 'You can create multi-Region KMS keys for all supported KMS key types: symmetric encryption KMS keys, HMAC KMS keys, asymmetric encryption KMS keys, and asymmetric signing KMS keys.' Cross-confirmed against the live AWS API docs and the 2021-06 multi-Region-keys launch post. HMAC keys DO support MultiRegion; the check unconditionally rejected a valid request shape and was removed rather than re-coded. Two pre-existing tests encoded the false premise and were corrected, not weakened: TestKMSCreateKeyIncompatibleSpecUsage (signing_internal_test.go) asserted ErrInvalidKeyUsage for genuinely-incompatible KeySpec/KeyUsage pairs -- corrected to ErrUnsupportedParameter, matching (1) above; TestCreateKeyValidations's hmac_multiregion case (replication_test.go) asserted wantErr:true for HMAC+MultiRegion -- corrected to wantErr:false (renamed hmac_multiregion_allowed) per (2). TestHandlerCreateKeyHMACMultiRegionRejected (handler_replication_maintenance_test.go) was removed outright, superseded by TestHandler_CreateKey_HMACMultiRegion_ViaHTTP (handler_keys_test.go), which now asserts 200 with the requested KeySpec/KeyUsage/MultiRegion round-tripped. New regression test TestHandler_CreateKey_KeySpecKeyUsageMismatch_ViaHTTP (handler_keys_test.go) drives the full HTTP handler for RSA_2048+GENERATE_VERIFY_MAC and asserts JSON Type is UnsupportedOperationException, not InvalidKeyUsageException; confirmed failing pre-fix with the exact predicted values (400/InvalidKeyUsageException). errtargetaudit -dir kms shows 0 CreateKey findings after the fix (unrelated pre-existing DescribeKey/DisableKey/EnableKey/ScheduleKeyDeletion findings are untouched false positives per the 8u3f entry above). Not authorization/grant/policy-related -- pure KeySpec/KeyUsage/MultiRegion request validation. Gates: go test -race -count=1 ./services/kms/... and golangci-lint run ./services/kms/... both green.
• RESOLVED 2026-09-07 (gopherstack-4ra7): the two shared-helper landmines i4q8 called out separately (differing caller declared sets defeat the per-call-site rule). Caller lists re-verified by grep, not trusted: validateEncryptionContextSize (crypto.go) is reached by GenerateDataKey and GenerateDataKeyWithoutPlaintext (both via the shared generateDataKey helper), GenerateDataKeyPair and GenerateDataKeyPairWithoutPlaintext (both via the shared generateDataKeyPair helper), Encrypt, Decrypt and ReEncrypt (via validateReEncryptInput) -- 7 ops, matching the issue exactly. Re-extracted all 7 declared sets from kms@v1.55.4 deserializers.go: none has a size/length/quota-shaped code (LimitExceededException is absent from every one of the 7; each set is dominated by key-state/grant-token/key-usage codes). No plumbing added: threading a per-caller sentinel through the helper, or returning a neutral sentinel for callers to translate, would add real cost (a new parameter or wrapper type threaded through 7 call sites) to select between codes that ALL fail to fit -- worse than the landmine it would replace. Kept ErrValidation (ValidationException) and documented why it is not a landmine here despite gopherstack-q9bs's structural/operation-logic distinction: an EncryptionContext byte-size cap is a single-field length constraint independent of any other field or resource state, the same shape as q9bs's own GetPublicKey malformed-DER-blob example, not a cross-field business rule like CreateKey's KeySpec/KeyUsage pairing (5rjn, above) -- so it is the pre-dispatch/structural class q9bs confirmed the allowlist entry covers, not the operation-logic class it doesn't. resolveKeyID's (store.go) cache-corruption branch (a failed type assertion on a sync.Map load) was independently verified unreachable, not assumed from the issue text: grep confirms the only two Store calls into keyIDResolutionCache (store.go:449, 460) always write cachedResolution, and Restore (persistence.go:322, 344) clears the cache via clearResolutionCache rather than repopulating it from snapshot data -- no code path, including snapshot/restore, can produce a non-cachedResolution entry. Same shape as gopherstack-t8iz's stepfunctions finding: an honest landmine, not a per-op design question, since there is no reachable per-op fit to resolve. Both sites already carried a one-line landmine comment; strengthened in place (crypto.go, store.go) to record the caller lists / unreachability proof and the q9bs cross-reference, rather than adding a second RESOLVED-but-changed-nothing note without pointing at the evidence. No production behavior changed for either site. Gates: go test -race -count=1 ./services/kms/... and golangci-lint run ./services/kms/... both green.
• RESOLVED 2026-09-07 (gopherstack-jyi3): CreateGrant's invalid-Operations-entry check (grants.go) was left an open question by 3b06f1f3d (filed to decide alongside 5rjn) and then swept, with its landmine comment removed, by 905209940's blanket 32-site ValidationException ruling -- but never individually re-verified against CreateGrant's own declared set or GrantOperation's shape. Re-derived: CreateGrant's deserializeOpError (kms@v1.55.4) declares DependencyTimeoutException/DisabledException/DryRunOperationException/InvalidArnException/InvalidGrantTokenException/KMSInternalException/KMSInvalidStateException/LimitExceededException/NotFoundException -- no UnsupportedOperationException, so 5rjn's CreateKey KeySpec/KeyUsage remedy does not transfer (that op declares the code CreateGrant simply doesn't have). Checked GrantOperation directly in api-2.json: a plain enum-constrained string shape, no cross-field rule -- the same single-field structural class as q9bs's GetPublicKey malformed-blob precedent (and gopherstack-4ra7's EncryptionContext-size precedent), not the cross-field business-rule class 5rjn's KeySpec/KeyUsage pairing needed its own declared code for. So ErrValidation is correct here specifically, not merely by blanket inheritance. No code or test change (the site's behavior was already correct); grants.go's check now carries a short comment recording this, since 905209940 left it bare. gopherstack-i4q8's original 36-site inventory undercounted CreateGrant's other undeclared-code sites too (see gaps entries above, all still-correct ErrLimitExceeded/ErrValidation calls).
• 2026-09-12 (reqfielddiff slice 6, gopherstack-xhu2t): ListKeyRotationsInput.IncludeKeyMaterial (ALL_KEY_MATERIAL) is entirely unmodeled -- honoring it means adding a synthetic 'first key material' RotationsListEntry plus tracking 'imported key material pending rotation' as a distinct generation, and this backend already has a documented precedent against exactly that: ImportKeyMaterialOutput's own doc comment (models.go) states 'this backend has no concept of multiple key-material generations per key.' Not implemented, consistent with that existing scope decision.
• 2026-09-12 (reqfielddiff slice 6, gopherstack-xhu2t): CreateCustomKeyStore/UpdateCustomKeyStoreInput.XksProxyVpcEndpointServiceOwner is accepted-and-dropped -- the real CustomKeyStoresListEntry response type (kms@v1.59.0 types/types.go:35+) has no field to round-trip it onto, and this backend models no XKS-proxy/VPC-endpoint-service state at all (CustomKeyStore only tracks CustomKeyStoreType/ConnectionState, matching the pre-existing 'deferred' entry above: 'no CloudHSM cluster or XKS proxy is modeled'). Nothing observable to fix.

Deferred

• Custom key store cryptographic connection/HSM simulation (ConnectCustomKeyStore is a pure state-machine transition; no CloudHSM cluster or XKS proxy is modeled, matching pre-existing scope). Re-audited 2026-07-23, still accurate -- no change.
• REMOVED 2026-07-23: GetKeyLastUsage was listed here as 'not a real AWS KMS operation'. That was wrong on every prior pass -- see the GetKeyLastUsage ops row above. It is now field-diffed and current.

More

• Full parity audit
• Service guide
• All services