DOC: configuration: rework the jwt_verify keyword documentation

Split the documentation in multiple sections:

- Explanation about what it does and how
- <alg> parameter with array of parameters
- <key> parameter with details about certificates and public keys
- Return value

Others changes:

- certificates does not need to be known during configuration parsing
- differences between public key and certificate

Author: wlallemand

doc/configuration.txt

@@ -20591,52 +20591,78 @@ jwt_payload_query([<json_path>[,<output_type>]])
   compiled with USE_OPENSSL.
 
 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, a path to a public key or a path to a public certificate. When
-  using a public key, it 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). Certificates should be a regular PEM
-  certificate (starting with BEGIN CERTIFICATE). If a full-on certificate is
-  used, it can either be used directly in the converter or passed via a
-  variable if it was already known by haproxy (previously loaded in a crt-store
-  for instance).
-  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.
 
+  Performs a signature verification for the JSON Web Token (JWT) given in input
+  by using the <alg> algorithm and the <key> parameter.
   For now, only JWS tokens using the Compact Serialization format can be
-  processed (three dot-separated base64-url encoded strings). All the
-  algorithms mentioned in section 3.1 of RFC7518 are managed (HS, ES, RS and PS
-  with the 256, 384 or 512 key sizes, as well as the special "none" case).
-
-  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 key or certificate that can be used to validate the token's signature.
-  All the public keys and certificates 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 and every
-  certificate used must be loaded by haproxy (in a crt-store or mentioned
-  explicitly in a 'jwt_verify' call). Passing a variable as second parameter is
-  then not advised unless you only use certificates that fill one of those
-  prerequisites.
-
+  processed (three dot-separated base64-url encoded strings).
   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 JSONs once
   decoded for instance, and no checks are performed regarding their respective
   contents.
 
+  - <alg> can be either a string or a variable name (See also "set-var") that
+    holds the name of the algorithm used to verify.
+
+    Algorithms mentioned in section 3.1 of RFC7518 are managed:
+
+   +--------------+---------------------------------------------------------+
+   | "alg" Param  | Digital Signature or MAC Algorithm                      |
+   | Value        |                                                         |
+   +--------------+---------------------------------------------------------+
+   | HS256        | HMAC using SHA-256                                      |
+   | HS384        | HMAC using SHA-384                                      |
+   | HS512        | HMAC using SHA-512                                      |
+   | RS256        | RSASSA-PKCS1-v1_5 using SHA-256                         |
+   | RS384        | RSASSA-PKCS1-v1_5 using SHA-384                         |
+   | RS512        | RSASSA-PKCS1-v1_5 using SHA-512                         |
+   | ES256        | ECDSA using P-256 and SHA-256                           |
+   | ES384        | ECDSA using P-384 and SHA-384                           |
+   | ES512        | ECDSA using P-521 and SHA-512                           |
+   | PS256        | RSASSA-PSS using SHA-256 and MGF1 with SHA-256          |
+   | PS384        | RSASSA-PSS using SHA-384 and MGF1 with SHA-384          |
+   | PS512        | RSASSA-PSS using SHA-512 and MGF1 with SHA-512          |
+   | none         | No digital signature or MAC performed                   |
+   +--------------+---------------------------------------------------------+
+
+  - <key> can be either a string or a variable name (See also "set-var") that
+    holds a secret, a public key path or a certificate path.
+
+    Secrets are only applicable when using HMAC algorithms.
+
+    Public keys must be in either 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). Public keys must be available during the
+    configuration parsing and cannot be updated or loaded at runtime unlike
+    certificates.
+
+    Certificates must be standard PEM certificates (starting with BEGIN
+    CERTIFICATE). When using a certificate its path can be passed directly to
+    the converter or referenced via a variable. Certificates can be either
+    declared in a crt-store, or dynamically loaded via the stats socket.
+
+    All the public keys and certificates 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.
+
+    It is possible to update certificates dynamically and add new certificates
+    using the stats socket. See also "set ssl cert" and "new ssl cert" in the
+    management guide.
+
+  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.
+
   The possible return values are the following :
 
   +----+----------------------------------------------------------------------+
   | ID | message                                                              |
   +----+----------------------------------------------------------------------+
-  |  0 | "Verification failure"                                               |
   |  1 | "Verification success"                                               |
+  |  0 | "Verification failure"                                               |
   | -1 | "Unknown algorithm (not mentioned in RFC7518)"                       |
   | -2 | "Unmanaged algorithm"                                                |
   | -3 | "Invalid token"                                                      |