add functions to access unverified payload

[frasertweedale]

Fixes: #126

[frasertweedale]

@julmb would you please review this PR and give feedback about whether it meet your needs?

[julmb]

This does work for my use case, although I am a little surprised.

The PR uses language like "footgun", "utmost caution", "exceptional use case", and "most applications should use" to make it clear that this is not a recommended or common way to interact with the library. However, I was under the impression that what I was doing (using a JWT to authorize requests to a web service) would be a pretty common use case for JWTs, and that furthermore verifying the expiration date on the client side would be a natural requirement for this process.

I am very inexperienced with web development, so I am wondering if I am doing something strange here, or maybe the service I am trying to use is misusing JWTs in some way (for reference, https://webservices.openplanet.dev/auth). If this use case is somewhat common, maybe it deserves slightly less discouragement by the documentation (although I do understand the need to point users in the right direction when it comes to library usage, especially when the implications are security-relevant).

[frasertweedale]

This does work for my use case, although I am a little surprised.

The PR uses language like "footgun", "utmost caution", "exceptional use case", and "most applications should use" to make it clear that this is not a recommended or common way to interact with the library. However, I was under the impression that what I was doing (using a JWT to authorize requests to a web service) would be a pretty common use case for JWTs, and that furthermore verifying the expiration date on the client side would be a natural requirement for this process.

I am very inexperienced with web development, so I am wondering if I am doing something strange here, or maybe the service I am trying to use is misusing JWTs in some way (for reference, https://webservices.openplanet.dev/auth). If this use case is somewhat common, maybe it deserves slightly less discouragement by the documentation (although I do understand the need to point users in the right direction when it comes to library usage, especially when the implications are security-relevant).

The general issue is with an application reading and taking action upon unverified data from a third party. In your specific case, if a malicious party is able to modify the contents of the JWT and you act upon it without verification, what could they do?

• Trigger failures in your own application by invalid/huge JWT data. For example, hash-flooding attack. The JSON library or other mitigations should protect against this.
• Alter/add/remove claims in the JWT. In this case they could make the JWT appear expired (perhaps triggering a loop condition to retrieve a new JWT), or otherwise corrupt the value such that signature verification would fail (perhaps triggering a denial of service when your application reaches back to the API for which the token was issued). Both of these could provoke a Denial-of-Service in your own application.

If you do not have the public (or in case of HMAC, shared) key for verifying the JWT, well, you can't verify it. If you trust the issuing service and assume it has not been compromised, you have no better solution than to read and act upon the "exp" field from the (unverified) payload. Alternatively, if the lifetime of a JWT is conveyed or documented elsewhere, you could rely on that and not bother to read the JWT payload.

In summary:

• Your JWT use case is common and normal.
• Reading the expiry time to know when token needs refresh: this makes sense.
• In general, using any unverified data in an application is to be done with great caution. You must carefully analyse your trust and threat models.
• The particular thing you want to do is probably fine, but you should satisfy yourself having regard to the previous point.

[julmb]

I see, thank you for the detailed explanation, those are a lot of things I did not consider. I will have to think about these things properly once my application is a little further along in development. For now, I am satisfied knowing that I am neither (1) completely misusing JWTs in some way nor (2) somehow taking on risks other than the general ones you mentioned when it comes to handling untrusted data.

[endgame]

Is it worth mentioning the principle of cryptographic doom in the haddocks of these functions?

[frasertweedale]

Is it worth mentioning the principle of cryptographic doom in the haddocks of these functions?

I think the current admonitions in the doc are sufficient.