TimedJSONWebSignatureSerializer vs URLSafeTimedSerializer: When should I use what?

Question

I found TimedJSONWebSignatureSerializer and URLSafeTimedSerializer. I wonder why those two methods exist. As a user of that library, what are reasons to chose one or the other?

What I've tried

I didn't even find TimedJSONWebSignatureSerializer in the docs, but only something general about JSON Web Signatures.

Looking at the inheritance did not help:

• TimedJSONWebSignatureSerializer inherits from JSONWebSignatureSerializer
• URLSafeTimedSerializer inherits from URLSafeSerializerMixin, TimedSerializer

Looking at the constructors, I have the impression that both might be for the same use cases, but maybe the JSON Web Signatures are standardized while the other one isn't?

Looking at usage:

from itsdangerous import TimedJSONWebSignatureSerializer, URLSafeTimedSerializer

data = {"id": 42, "op": "foobar"}
max_age_s = 123

s1 = TimedJSONWebSignatureSerializer('secret', expires_in=max_age_s)
s1_dumped = s1.dumps(data)
s1_loaded = s1.loads(s1_dumped)

s2 = URLSafeTimedSerializer('secret')
s2_dumped = s2.dumps(data)
s2_loaded = s2.loads(s2_dumped, max_age=max_age_s)

Then

>>> s1_dumped
b'eyJhbGciOiJIUzUxMiIsImlhdCI6MTU2MTEwNDU0NSwiZXhwIjoxNTYxMTA4MTQ1fQ.eyJpZCI6NDIsIm9wIjoiZm9vYmFyIn0.sux9j4OpBc7-se16WSrZvp-bll5ZeyCQR_CumSE7jPQ9-w_kTqpr0OtwhJp8S766Xt1W3fKSE-dl2z8q9ZAhzg'
>>> s2_dumped
'eyJpZCI6NDIsIm9wIjoiZm9vYmFyIn0.XQyQoQ.-6n5Jw6TWz8tsyfgagyS5_fHjAY'
>>> len(s1_dumped)
185
>>> len(s2_dumped)
66

Hence the JSON Web Signature is way longer. What do you win by having it?

Answer 1

I have the impression that both might be for the same use cases but maybe the JSON Web Signatures are standardized while the other one isn't?

The use case of both methods is almost the same, but without extra programming steps you need the Itsdangerous lib on both sides (sender and receiver) when you use the URLSafeTimedSerializer while TimedJSONWebSignatureSerializer is more flexible, because the JSON Web Signature format is standardized. This extends the use case of TimedJSONWebSignatureSerializer to communication with software written in other languages, because it's based on JSON format and there are libs available for many different languages.

In fact, JSON Web Sigbnature and generally the JSON Web Tokens are quite often used as Authorization tokens, but not limited to that use case.

The different results of your examples have two reasons:

• The JSON Web Signature format requires a header and a payload part, which are both in JSON format, and the header also contains a mandatory alg claim, which

identifies the cryptographic algorithm used to secure the JWS.

• The two methods use different cryptographic algorithms for the signature: URLSafeTimedSerializer uses by default SHA1

Internally itsdangerous uses HMAC and SHA1, (according to the docs)

while TimedJSONWebSignatureSerializer uses SHA512, see the decoded header:

{ "alg": "HS512", "iat": 1561104545, "exp": 1561108145 }

The latter is longer, but also safer. (see SHA1 vs. SHA256)

I hope this explains the different use cases and results of these methods.

Btw. it's "interesting" to see the iat (issued at) and exp (expires at) claims in the header, never seen this before. Usually they are part of the payload. This raises the question why would you use Itsdangerous at all if you want JWS/JWT output, as there are many other libs available for that, also for python.