Криптографическая подпись

Использование аргумента salt

Если вы не хотите, чтобы каждое вхождение определённой строки имело одинаковую хеш-подпись, можно использовать необязательный аргумент salt класса Signer. Соль инициализирует функцию хеширования подписи, используя как соль, так и ваш SECRET_KEY:

>>> signer = Signer()
>>> signer.sign("My string")
'My string:v9G-nxfz3iQGTXrePqYPlGvH79WTcIgj1QIQSUODTW0'
>>> signer.sign_object({"message": "Hello!"})
'eyJtZXNzYWdlIjoiSGVsbG8hIn0:bzb48DBkB-bwLaCnUVB75r5VAPUEpzWJPrTb80JMIXM'
>>> signer = Signer(salt="extra")
>>> signer.sign("My string")
'My string:YMD-FR6rof3heDkFRffdmG4pXbAZSOtb-aQxg3vmmfc'
>>> signer.unsign("My string:YMD-FR6rof3heDkFRffdmG4pXbAZSOtb-aQxg3vmmfc")
'My string'
>>> signer.sign_object({"message": "Hello!"})
'eyJtZXNzYWdlIjoiSGVsbG8hIn0:-UWSLCE-oUAHzhkHviYz3SOZYBjFKllEOyVZNuUtM-I'
>>> signer.unsign_object(
...     "eyJtZXNzYWdlIjoiSGVsbG8hIn0:-UWSLCE-oUAHzhkHviYz3SOZYBjFKllEOyVZNuUtM-I"
... )
{'message': 'Hello!'}

Использование соли таким образом помещает разные подписи в отдельные пространства имён. Подпись из одного пространства имён (с определённым значением соли) нельзя использовать для проверки той же строки открытого текста в другом пространстве имён, где задано другое значение соли. Это не позволяет злоумышленнику использовать подписанную строку, созданную в одной части кода, в качестве входных данных для другой части кода, которая создаёт и проверяет подписи с другой солью.

В отличие от SECRET_KEY, аргумент соли не обязательно хранить в секрете.

Проверка значений с временной меткой

TimestampSigner — это подкласс Signer, который добавляет к значению подписанную временную метку. Это позволяет убедиться, что подписанное значение было создано в течение заданного периода времени:

>>> from datetime import timedelta
>>> from django.core.signing import TimestampSigner
>>> signer = TimestampSigner()
>>> value = signer.sign("hello")
>>> value
'hello:1stLqR:_rvr4oXCgT4HyfwjXaU39QvTnuNuUthFRCzNOy4Hqt0'
>>> signer.unsign(value)
'hello'
>>> signer.unsign(value, max_age=10)
SignatureExpired: Signature age 15.5289158821 > 10 seconds
>>> signer.unsign(value, max_age=20)
'hello'
>>> signer.unsign(value, max_age=timedelta(seconds=20))
'hello'

class TimestampSigner(*, key=None, sep=':', salt=None, algorithm='sha256') [исходный код]

sign(value) [исходный код]

Подписывает value и добавляет к нему текущую временную метку.

unsign(value, max_age=None) [исходный код]

Проверяет, было ли value подписано менее max_age секунд назад; в противном случае вызывает SignatureExpired. Параметр max_age может принимать целое число или объект datetime.timedelta.

sign_object(obj, serializer=JSONSerializer, compress=False)

Кодирует, при необходимости сжимает, добавляет текущую временную метку и подписывает сложную структуру данных (например, список, кортеж или словарь).

unsign_object(signed_obj, serializer=JSONSerializer, max_age=None)

Проверяет, было ли signed_obj подписано менее max_age секунд назад; в противном случае вызывает SignatureExpired. Параметр max_age может принимать целое число или объект datetime.timedelta.

Защита сложных структур данных

Для защиты списка, кортежа или словаря можно использовать методы Signer.sign_object() и unsign_object() либо функции dumps() или loads() из модуля signing (это сокращённые варианты TimestampSigner(salt='django.core.signing').sign_object()/unsign_object()). Под капотом они используют сериализацию JSON. Благодаря JSON, даже если ваш SECRET_KEY будет украден, злоумышленник не сможет выполнять произвольные команды, используя уязвимости формата pickle:

>>> from django.core import signing
>>> signer = signing.TimestampSigner()
>>> value = signer.sign_object({"foo": "bar"})
>>> value
'eyJmb28iOiJiYXIifQ:1stLrZ:_QiOBHafwucBF9FyAr54qEs84ZO1UdsO1XiTJCvvdno'
>>> signer.unsign_object(value)
{'foo': 'bar'}
>>> value = signing.dumps({"foo": "bar"})
>>> value
'eyJmb28iOiJiYXIifQ:1stLsC:JItq2ZVjmAK6ivrWI-v1Gk1QVf2hOF52oaEqhZHca7I'
>>> signing.loads(value)
{'foo': 'bar'}

В силу особенностей JSON (в нём нет встроенного различия между списками и кортежами), если передать кортеж, signing.loads(object) вернёт список:

>>> from django.core import signing
>>> value = signing.dumps(("a", "b", "c"))
>>> signing.loads(value)
['a', 'b', 'c']

dumps(obj, key=None, salt='django.core.signing', serializer=JSONSerializer, compress=False) [исходный код]

Возвращает URL-безопасную подписанную строку JSON в base64, сжатую с помощью gzip. Сериализованный объект подписывается с использованием TimestampSigner.

loads(string, key=None, salt='django.core.signing', serializer=JSONSerializer, max_age=None, fallback_keys=None) [исходный код]

Выполняет обратное преобразование для dumps() и вызывает BadSignature, если подпись не прошла проверку. При наличии параметра проверяет max_age (в секундах).