Clearly warn against computing algorithms from the token’s alg (#647)

Signed-off-by: Anders Kaseorg <andersk@mit.edu>

docs/algorithms.rst

@@ -57,3 +57,15 @@ of allowed algorithms:
 
 In the above case, if the JWT has any value for its alg header other than
 HS512 or HS256, the claim will be rejected with an ``InvalidAlgorithmError``.
+
+.. warning::
+
+   Do **not** compute the ``algorithms`` parameter based on the
+   ``alg`` from the token itself, or on any other data that an
+   attacker may be able to influence, as that might expose you to
+   various vulnerabilities (see `RFC 8725 §2.1
+   <https://www.rfc-editor.org/rfc/rfc8725.html#section-2.1>`_). Instead,
+   either hard-code a fixed value for ``algorithms``, or configure it
+   in the same place you configure the ``key``. Make sure not to mix
+   symmetric and asymmetric algorithms that interpret the ``key`` in
+   different ways (e.g. HS\* and RS\*).

docs/api.rst

@@ -28,9 +28,18 @@ API Reference
 
     :param list algorithms: allowed algorithms, e.g. ``["ES256"]``
 
-        .. note:: It is highly recommended to specify the expected ``algorithms``.
-
-        .. note:: It is insecure to mix symmetric and asymmetric algorithms because they require different kinds of keys.
+        .. warning::
+
+           Do **not** compute the ``algorithms`` parameter based on
+           the ``alg`` from the token itself, or on any other data
+           that an attacker may be able to influence, as that might
+           expose you to various vulnerabilities (see `RFC 8725 §2.1
+           <https://www.rfc-editor.org/rfc/rfc8725.html#section-2.1>`_). Instead,
+           either hard-code a fixed value for ``algorithms``, or
+           configure it in the same place you configure the
+           ``key``. Make sure not to mix symmetric and asymmetric
+           algorithms that interpret the ``key`` in different ways
+           (e.g. HS\* and RS\*).
 
     :param dict options: extended decoding and validation options