From: Remi Tricot-Le Breton <rlebreton@haproxy.com>
Date: Mon, 30 Jun 2025 14:56:23 +0000 (+0200)
Subject: DOC: Fix 'jwt_verify' converter doc
X-Git-Tag: v3.3-dev3~67
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5c3d0a554b3db024aef62826b67821ca6a1383ee;p=thirdparty%2Fhaproxy.git

DOC: Fix 'jwt_verify' converter doc

Contrary to what the doc says, the jwt_verify converter only works with
a public key and not a full certificate for certificate based protocols
(everything but HMAC).

This patch should be backported up to 2.8.
---

diff --git a/doc/configuration.txt b/doc/configuration.txt
index 9859a9a52..895dab118 100644
--- a/doc/configuration.txt
+++ b/doc/configuration.txt
@@ -20518,11 +20518,14 @@ jwt_payload_query([<json_path>[,<output_type>]])
 jwt_verify(<alg>,<key>)
   Performs a signature verification for the JSON Web Token (JWT) given in input
   by using the <alg> algorithm and the <key> parameter, which should either
-  hold a secret or a path to a public certificate. Returns 1 in case of
-  verification success, 0 in case of verification error and a strictly negative
-  value for any other error. Because of all those non-null error return values,
-  the result of this converter should never be converted to a boolean. See
-  below for a full list of the possible return values.
+  hold a secret or a path to a public key. The public key should either be in
+  the PKCS#1 format (for RSA keys, starting with BEGIN RSA PUBLIC KEY) or SPKI
+  format (Subject Public Key Info, starting with BEGIN PUBLIC KEY).
+  Returns 1 in case of verification success, 0 in case of verification failure
+  and a strictly negative value for any other error. Because of all those
+  non-null error return values, the result of this converter should never be
+  converted to a boolean. See below for a full list of the possible return
+  values.
 
   For now, only JWS tokens using the Compact Serialization format can be
   processed (three dot-separated base64-url encoded strings). All the
@@ -20531,16 +20534,16 @@ jwt_verify(<alg>,<key>)
 
   If the used algorithm is of the HMAC family, <key> should be the secret used
   in the HMAC signature calculation. Otherwise, <key> should be the path to the
-  public certificate that can be used to validate the token's signature. All
-  the certificates that might be used to verify JWTs must be known during init
-  in order to be added into a dedicated certificate cache so that no disk
-  access is required during runtime. For this reason, any used certificate must
-  be mentioned explicitly at least once in a jwt_verify call. Passing an
-  intermediate variable as second parameter is then not advised.
+  public key that can be used to validate the token's signature. All the public
+  keys that might be used to verify JWTs must be known during init in order to
+  be added into a dedicated cache so that no disk access is required during
+  runtime. For this reason, any used public key must be mentioned explicitly at
+  least once in a jwt_verify call. Passing an intermediate variable as second
+  parameter is then not advised.
 
   This converter only verifies the signature of the token and does not perform
   a full JWT validation as specified in section 7.2 of RFC7519. We do not
-  ensure that the header and payload contents are fully valid JSON's once
+  ensure that the header and payload contents are fully valid JSONs once
   decoded for instance, and no checks are performed regarding their respective
   contents.
 
@@ -20567,7 +20570,7 @@ jwt_verify(<alg>,<key>)
      http-request set-var(txn.bearer) http_auth_bearer
      http-request set-var(txn.jwt_alg) var(txn.bearer),jwt_header_query('$.alg')
      http-request deny unless { var(txn.jwt_alg) -m str "RS256" }
-     http-request deny unless { var(txn.bearer),jwt_verify(txn.jwt_alg,"/path/to/crt.pem") 1 }
+     http-request deny unless { var(txn.bearer),jwt_verify(txn.jwt_alg,"/path/to/pubkey.pem") 1 }
 
 language(<value>[,<default>])
   Returns the value with the highest q-factor from a list as extracted from the