From d724d619425245c979b8f99a238a8e11a2ee0996 Mon Sep 17 00:00:00 2001 From: Thibault Meunier Date: Tue, 1 Sep 2026 10:11:59 +0200 Subject: [PATCH] docs: clarify production key use --- README.md | 2 +- packages/web-bot-auth/README.md | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index d7b0415..8e64e47 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ Cloudflare Research provides a live environment at [http-message-signatures-exam Use this deployment to test an implementation. -1. It validates the presence of a `Signature` header signed [RFC9421 ed25519 test key](./examples/rfc9421-keys/ed25519.pem), +1. It validates the presence of a `Signature` header signed with a [published RFC 9421 test key](./examples/rfc9421-keys/ed25519.pem), which [must not be used in production](./packages/web-bot-auth/#security-considerations), 2. It exposes a bot directory on [/.well-known/http-message-signatures-directory](https://http-message-signatures-example.research.cloudflare.com/.well-known/http-message-signatures-directory), 3. It serves debug tools for request signatures, JWK key IDs, and directories. diff --git a/packages/web-bot-auth/README.md b/packages/web-bot-auth/README.md index 6e61ec1..a589080 100644 --- a/packages/web-bot-auth/README.md +++ b/packages/web-bot-auth/README.md @@ -41,8 +41,8 @@ const request = new Request("https://example.com", { headers: { "Signature-Agent": signatureAgent }, }); -// This is a testing-only private key/public key pair described in RFC 9421 Appendix B.1.4 -// Also available at https://github.com/cloudflareresearch/web-bot-auth/blob/main/examples/rfc9421-keys/ed25519.json +// Published RFC 9421 test key. Never use it in production; see Security Considerations below. +// Fixture: https://github.com/cloudflareresearch/web-bot-auth/blob/main/examples/rfc9421-keys/ed25519.json const RFC_9421_ED25519_TEST_KEY = { kty: "OKP", crv: "Ed25519", @@ -109,7 +109,7 @@ const authenticated = await verify(signedRequest, { ## Security Considerations -This software has not been audited. Please use at your sole discretion. +This software has not been audited. Use it at your sole discretion. RFC test keys [must not be used in production](https://datatracker.ietf.org/doc/html/draft-meunier-webbotauth-httpsig-protocol-02#section-6.8). For production, [generate a unique asymmetric key](https://datatracker.ietf.org/doc/html/draft-meunier-webbotauth-httpsig-protocol-02#section-6.4) with [Web Crypto](https://github.com/cloudflare/web-bot-auth/tree/main/packages/jsonwebkey-thumbprint#usage) or [OpenSSL](https://developers.cloudflare.com/bots/concepts/bot/verified-bots/web-bot-auth/#1-generate-a-valid-signing-key). Publish only its public JWK values. [Overlap old and new public keys during rotation](https://datatracker.ietf.org/doc/html/draft-meunier-webbotauth-httpsig-protocol-02#section-5.5.2). ## License