Skip to content

fix(webhook): handle non-ASCII signatures gracefully in secure_compare (#1991) - #1995

Open
jaideepkrishna2008-ui wants to merge 4 commits into
stripe:masterfrom
jaideepkrishna2008-ui:fix/webhook-non-ascii-signature
Open

jaideepkrishna2008-ui wants to merge 4 commits into
stripe:masterfrom
jaideepkrishna2008-ui:fix/webhook-non-ascii-signature

Conversation

@jaideepkrishna2008-ui

Copy link
Copy Markdown

Why?

Fixes #1991.

WebhookSignature.verify_header raised an unhandled TypeError when a v1 value in the Stripe-Signature header contained a non-ASCII character (e.g., t=1,v1=é), instead of raising SignatureVerificationError. This caused webhook handlers that catch ValueError and SignatureVerificationError to fail with unhandled 500 errors on invalid external requests.

secure_compare in stripe/_util.py passed both string arguments directly to standard library hmac.compare_digest, which only supports ASCII strings.

What?

  • Updated secure_compare in stripe/_util.py to gracefully catch TypeError and fall back to comparing UTF-8 encoded bytes with hmac.compare_digest in constant time.
  • Added regression test test_raise_on_non_ascii_signature_in_header in tests/test_webhook.py verifying that non-ASCII signatures raise SignatureVerificationError.
  • Added Hark changefile at .hark/changes/2026-11-15_jaideepkrishna2008-ui_webhook-non-ascii-signature.change.md.

See Also

Configuration

  • skip-changefile: This PR is not a user-facing change, so there's no changefile.

stripe#1991)

WebhookSignature.verify_header raised a TypeError when encountering
a non-ASCII character in header signatures because stdlib hmac.compare_digest
does not support non-ASCII string comparisons. Fall back to UTF-8 encoded
bytes comparison in secure_compare so invalid non-ASCII signatures raise
SignatureVerificationError as expected instead of an unhandled TypeError.

Fixes stripe#1991
@jaideepkrishna2008-ui
jaideepkrishna2008-ui requested a review from a team as a code owner November 15, 2026 14:05
@jaideepkrishna2008-ui
jaideepkrishna2008-ui requested review from ramya-stripe and removed request for a team November 15, 2026 14:05
@cla-assistant

cla-assistant Bot commented Nov 15, 2026 •

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@ajaykr0905 ajaykr0905 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this fix. I ran the new test on master and it fails with the TypeError from #1991. On this branch it passes, and the webhook tests, flake8, ruff and pyright are clean.

I have two points:

  1. A header with a lone surrogate, such as t=1,v1=\udcff, still raises UnicodeEncodeError and not SignatureVerificationError. If you use .encode("utf-8", "surrogatepass"), the result is False for this case.

  2. The except TypeError block also returns False for other bad types, such as None or bytes against str. Before, these raised. I think it is better to change only the str and str case and raise again for all other types.

Can you also add a test for a header with a non-ASCII v1 before a valid v1? This branch accepts that header correctly, but no test checks it.

…types in secure_compare

Address review feedback from @ajaykr0905:
- Use surrogatepass error handling in UTF-8 encoding to prevent UnicodeEncodeError on lone surrogates.
- Only handle the str and str case under TypeError; re-raise for non-string types.
- Add test coverage for lone surrogates, invalid types, and headers containing non-ASCII v1 before valid v1.
@jaideepkrishna2008-ui

Copy link
Copy Markdown
Author

Thanks for the thorough review, @ajaykr0905! I've updated the implementation and added the requested tests:

  1. Lone surrogates (surrogatepass): Updated to val.encode("utf-8", "surrogatepass") in secure_compare so lone surrogates (e.g. t=1,v1=\udcff) are encoded without raising UnicodeEncodeError and return False.
  2. Type error handling: Changed the except TypeError block to only convert when both arguments are str. For all other invalid types (e.g. None or bytes vs str), TypeError is re-raised as before.
  3. Additional test coverage:
    • Added test verifying a header with a lone surrogate t=1,v1=\udcff raises SignatureVerificationError.
    • Added test verifying a header with a non-ASCII v1 before a valid v1 passes verification.
    • Added test verifying invalid types passed to secure_compare raise TypeError.

@ajaykr0905 ajaykr0905 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the update! I ran my checks again on 839d063.

  1. verify_header with t=1,v1=\udcff now raises SignatureVerificationError, not UnicodeEncodeError.
  2. secure_compare(None, "signature") and secure_compare(b"bytes", "str") now raise the same TypeError as on master.
  3. test_header_with_non_ascii_v1_before_valid_v1 fails on master and passes here.

Webhook and util tests: 64 passed, 16 skipped. flake8 and ruff are clean.

Two small points:

  • pyright tests/test_webhook.py reports 2 errors at lines 245 and 247 ("_util" is not a known member of module "stripe"). CI does not check this file. from stripe._util import secure_compare fixes it.
  • No test checks the True result of the new str fallback. When I replaced it with return False, the tests still passed. Can you add assert secure_compare("é", "é")?

…for non-ASCII strings

Address follow-up review from @ajaykr0905:
- Import secure_compare directly from stripe._util to satisfy pyright.
- Add test asserting True equality (and inequality) for non-ASCII strings in secure_compare.
@jaideepkrishna2008-ui

Copy link
Copy Markdown
Author

Thanks again, @ajaykr0905! I've updated the tests in commit e8317af:

  1. Direct import for pyright: Changed to from stripe._util import secure_compare so pyright tests/test_webhook.py resolves the import cleanly without accessing private members on stripe.
  2. Explicit non-ASCII equality test: Added test_secure_compare_non_ascii_strings asserting assert secure_compare("é", "é") and assert not secure_compare("é", "è") to explicitly verify the True fallback branch.

All 64 webhook/util tests pass (48 passed in webhook suite, 16 skipped).

@ajaykr0905 ajaykr0905 left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the quick update! I checked e8317af. pyright tests/test_webhook.py is now clean, and the webhook and util tests pass (65 passed, 16 skipped). The new test covers the True result of the fallback. This looks good to me.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

WebhookSignature.verify_header raises TypeError for a non-ASCII v1 signature

2 participants