Document the JSON form of PubSecKeyOptions buffer - #761
Merged
tsegismont merged 1 commit intoAug 25, 2026
Conversation
When PubSecKeyOptions are created from JSON the buffer field is a Buffer, which is represented in JSON as the base64 encoding of the key bytes rather than the PEM text. Nothing documented this, so pasting a PEM into JSON fails with "Illegal base64 character". - PubSecKeyOptions javadoc explains the JSON representation and how to obtain it (new PubSecKeyOptions().setBuffer(pem).toJson()) - vertx-auth-jwt docs gain a "Configuring keys from JSON" section with an example (AuthJWTExamples#example19) - PubSecKeyOptionsTest covers the JSON round trip and JWTAuthFromJsonTest proves a JSON configured provider verifies tokens signed by a setter configured one Fixes eclipse-vertx#596
tsegismont
force-pushed
the
issue-596-pubseckey-json-docs
branch
from
August 25, 2026 15:29
f8d0f00 to
f98bbd4
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #596
PubSecKeyOptions.bufferis aBuffer, so its JSON representation is the base64 encoding of the key bytes (standard Vert.xBuffer↔ JSON mapping via the generated converter), not the PEM text. That is consistent with the rest of Vert.x, but it was undocumented, and the docs' PEM examples lead users to paste the PEM into a JSON config and hitIllegalArgumentException: Illegal base64 character— exactly the report in #596 (the reporter eventually discovered the base64 form on their own).This PR does not change behaviour; it documents it and pins it with tests:
PubSecKeyOptionsjavadoc (class + bothsetBufferoverloads) explains the JSON representation and how to obtain it:new PubSecKeyOptions().setBuffer(pem).toJson().AuthJWTExamples#example19.PubSecKeyOptionsTest(common): setter →toJson()→ JSON-constructor round trip, base64 PEM loads into a usableJWK, raw PEM in JSON is rejected.JWTAuthFromJsonTest(jwt): a JWTAuth built from JSON config verifies a token signed by the setter-configured twin, and the resultingPubSecKeyOptionsare identical.I deliberately did not add a "starts with
-----BEGIN" heuristic to the JSON constructor: ambiguous decoding of key material in a security config type seems worse than a documented, uniform rule.