From 07885b85ce2f53a52f7840b48ac6560456b47c9b Mon Sep 17 00:00:00 2001 From: Johannes Jarbratt Date: Thu, 29 Apr 2021 18:36:32 +0900 Subject: [PATCH 1/3] Add warning and clarify how default values are set --- docs/api.rst | 28 ++++++++++++++++------------ 1 file changed, 16 insertions(+), 12 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 2b38b4a4..567575a2 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -43,19 +43,23 @@ API Reference :param dict options: extended decoding and validation options - * ``require=[]`` list of claims that must be present. E.g. ``require=["exp", "iat", "nbf"]``. - Only verifies that the claims exists. Does NOT verify that the claims are valid. - * ``verify_aud=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``aud`` (audience) claim matches ``audience`` - * ``verify_iat=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``iat`` (issued at) claim value is an integer - * ``verify_exp=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``exp`` (expiration) claim value is OK - * ``verify_iss=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``iss`` (issuer) claim matches ``issuer`` - * ``verify_nbf=True`` but will be ignored if ``verify_signature`` is ``False``. - Check that ``nbf`` (not before) is in the past * ``verify_signature=True`` verify the JWT cryptographic signature + * ``require=[]`` list of claims that must be present. + Example: ``require=["exp", "iat", "nbf"]``. + **Only verifies that the claims exists**. Does not verify that the claims are valid. + * ``verify_aud=verify_signature`` check that ``aud`` (audience) claim matches ``audience`` + * ``verify_iss=verify_signature`` check that ``iss`` (issuer) claim matches ``issuer`` + * ``verify_exp=verify_signature`` check that ``exp`` (expiration) claim value is in the future + * ``verify_iat=verify_signature`` check that ``iat`` (issued at) claim value is an integer + * ``verify_nbf=verify_signature`` check that ``nbf`` (not before) claim value is in the past + + .. warning:: + + ``exp``, ``iat`` and ``nbf`` will only be verified if present. + Please pass respective value to ``require`` if you want to make + sure that they are always present (and therefore always verified + if ``verify_exp``, ``verify_iat``, and ``verify_nbf`` respectively + is set to ``True``). :param Iterable audience: optional, the value for ``verify_aud`` check :param str issuer: optional, the value for ``verify_iss`` check From af65e9e02acaadd504c26637c19c98aff4615518 Mon Sep 17 00:00:00 2001 From: Johannes Jarbratt Date: Thu, 29 Apr 2021 19:20:08 +0900 Subject: [PATCH 2/3] Copy `jwt.decode` documentation to `jwt.decode_complete` --- docs/api.rst | 50 +++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 49 insertions(+), 1 deletion(-) diff --git a/docs/api.rst b/docs/api.rst index 567575a2..04984777 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -67,7 +67,55 @@ API Reference :rtype: dict :returns: the JWT claims -.. note:: TODO: Document PyJWS / PyJWT classes +.. function:: decode_complete(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0) + + Verify the ``jwt`` token signature and return the token claims. + + :param str jwt: the token to be decoded + :param str key: the key suitable for the allowed algorithm + + :param list algorithms: allowed algorithms, e.g. ``["ES256"]`` + + .. 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 + `_). 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 + + * ``verify_signature=True`` verify the JWT cryptographic signature + * ``require=[]`` list of claims that must be present. + Example: ``require=["exp", "iat", "nbf"]``. + **Only verifies that the claims exists**. Does not verify that the claims are valid. + * ``verify_aud=verify_signature`` check that ``aud`` (audience) claim matches ``audience`` + * ``verify_iss=verify_signature`` check that ``iss`` (issuer) claim matches ``issuer`` + * ``verify_exp=verify_signature`` check that ``exp`` (expiration) claim value is in the future + * ``verify_iat=verify_signature`` check that ``iat`` (issued at) claim value is an integer + * ``verify_nbf=verify_signature`` check that ``nbf`` (not before) claim value is in the past + + .. warning:: + + ``exp``, ``iat`` and ``nbf`` will only be verified if present. + Please pass respective value to ``require`` if you want to make + sure that they are always present (and therefore always verified + if ``verify_exp``, ``verify_iat``, and ``verify_nbf`` respectively + is set to ``True``). + + :param Iterable audience: optional, the value for ``verify_aud`` check + :param str issuer: optional, the value for ``verify_iss`` check + :param float leeway: a time margin in seconds for the expiration check + :rtype: dict + :returns: the JWT claims + +.. note:: TODO: Document PyJWS class Exceptions ---------- From 5a7a66b26da3be45a8ce7473c23eb8177b48ed10 Mon Sep 17 00:00:00 2001 From: Johannes Jarbratt Date: Fri, 30 Apr 2021 00:21:42 +0900 Subject: [PATCH 3/3] Customize `jwt.decode_complete` documentation --- docs/api.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/api.rst b/docs/api.rst index 04984777..d23d4bdd 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -69,7 +69,9 @@ API Reference .. function:: decode_complete(jwt, key="", algorithms=None, options=None, audience=None, issuer=None, leeway=0) - Verify the ``jwt`` token signature and return the token claims. + Identical to ``jwt.decode`` except for return value which is a dictionary containing the token header (JOSE Header), + the token payload (JWT Payload), and token signature (JWT Signature) on the keys "header", "payload", + and "signature" respectively. :param str jwt: the token to be decoded :param str key: the key suitable for the allowed algorithm @@ -113,7 +115,8 @@ API Reference :param str issuer: optional, the value for ``verify_iss`` check :param float leeway: a time margin in seconds for the expiration check :rtype: dict - :returns: the JWT claims + :returns: Decoded JWT with the JOSE Header on the key ``header``, the JWS + Payload on the key ``payload``, and the JWS Signature on the key ``signature``. .. note:: TODO: Document PyJWS class