加密签名

The golden rule of web application security is to never trust data from untrusted sources. Sometimes it can be useful to pass data through an untrusted medium. Cryptographically signed values can be passed through an untrusted channel safe in the knowledge that any tampering will be detected.

Django provides both a low-level API for signing values and a high-level API for setting and reading signed cookies, one of the most common uses of signing in web applications.

你可能还发现签名对以下方面很有用：

  • 生成“找回我的账户”URL 以发送给丢失密码的用户。
  • 确认存储在表单隐藏字段中的数据未被篡改。
  • 生成一次性的秘密 URL，允许临时访问受保护的资源，例如用户付费下载的文件。

Protecting SECRET_KEY and SECRET_KEY_FALLBACKS

当你使用 startproject 创建一个新的Django项目时，settings.py 文件会自动生成，并随机得到一个 SECRET_KEY 值。这个值是保证签名数据安全的关键——你必须保证这个值的安全，否则攻击者可以用它来生成自己的签名值。

SECRET_KEY_FALLBACKS can be used to rotate secret keys. The values will not be used to sign data, but if specified, they will be used to validate signed data and must be kept secure.

使用低级 API

Django’s signing methods live in the django.core.signing module. To sign a value, first instantiate a Signer instance:

  1. >>> from django.core.signing import Signer
  2. >>> signer = Signer()
  3. >>> value = signer.sign("My string")
  4. >>> value
  5. 'My string:GdMGD6HNQ_qdgxYP8yBZAdAIV1w'

The signature is appended to the end of the string, following the colon. You can retrieve the original value using the unsign method:

  1. >>> original = signer.unsign(value)
  2. >>> original
  3. 'My string'

If you pass a non-string value to sign, the value will be forced to string before being signed, and the unsign result will give you that string value:

  1. >>> signed = signer.sign(2.5)
  2. >>> original = signer.unsign(signed)
  3. >>> original
  4. '2.5'

If you wish to protect a list, tuple, or dictionary you can do so using the sign_object() and unsign_object() methods:

  1. >>> signed_obj = signer.sign_object({"message": "Hello!"})
  2. >>> signed_obj
  3. 'eyJtZXNzYWdlIjoiSGVsbG8hIn0:Xdc-mOFDjs22KsQAqfVfi8PQSPdo3ckWJxPWwQOFhR4'
  4. >>> obj = signer.unsign_object(signed_obj)
  5. >>> obj
  6. {'message': 'Hello!'}

详见:ref:signing-complex-data

If the signature or value have been altered in any way, a django.core.signing.BadSignature exception will be raised:

  1. >>> from django.core import signing
  2. >>> value += "m"
  3. >>> try:
  4. ...     original = signer.unsign(value)
  5. ... except signing.BadSignature:
  6. ...     print("Tampering detected!")
  7. ...

By default, the Signer class uses the SECRET_KEY setting to generate signatures. You can use a different secret by passing it to the Signer constructor:

  1. >>> signer = Signer(key="my-other-secret")
  2. >>> value = signer.sign("My string")
  3. >>> value
  4. 'My string:EkfQJafvGyiofrdGnuthdxImIJw'

class Signer(*, key=None, sep=’:’, salt=None, algorithm=None, fallback_keys=None)

Returns a signer which uses key to generate signatures and sep to separate values. sep cannot be in the URL safe base64 alphabet. This alphabet contains alphanumeric characters, hyphens, and underscores. algorithm must be an algorithm supported by hashlib, it defaults to 'sha256'. fallback_keys is a list of additional values used to validate signed data, defaults to SECRET_KEY_FALLBACKS.

4.2 版后已移除: Support for passing positional arguments is deprecated.

使用 salt 参数

If you do not wish for every occurrence of a particular string to have the same signature hash, you can use the optional salt argument to the Signer class. Using a salt will seed the signing hash function with both the salt and your SECRET_KEY:

  1. >>> signer = Signer()
  2. >>> signer.sign("My string")
  3. 'My string:GdMGD6HNQ_qdgxYP8yBZAdAIV1w'
  4. >>> signer.sign_object({"message": "Hello!"})
  5. 'eyJtZXNzYWdlIjoiSGVsbG8hIn0:Xdc-mOFDjs22KsQAqfVfi8PQSPdo3ckWJxPWwQOFhR4'
  6. >>> signer = Signer(salt="extra")
  7. >>> signer.sign("My string")
  8. 'My string:Ee7vGi-ING6n02gkcJ-QLHg6vFw'
  9. >>> signer.unsign("My string:Ee7vGi-ING6n02gkcJ-QLHg6vFw")
  10. 'My string'
  11. >>> signer.sign_object({"message": "Hello!"})
  12. 'eyJtZXNzYWdlIjoiSGVsbG8hIn0:-UWSLCE-oUAHzhkHviYz3SOZYBjFKllEOyVZNuUtM-I'
  13. >>> signer.unsign_object(
  14. ...     "eyJtZXNzYWdlIjoiSGVsbG8hIn0:-UWSLCE-oUAHzhkHviYz3SOZYBjFKllEOyVZNuUtM-I"
  15. ... )
  16. {'message': 'Hello!'}

以这种方式使用盐，会将不同的签名放入不同的命名空间。 来自一个命名空间的签名（一个特定的盐值）不能用于验证在使用不同盐值设置的不同命名空间中的同一明文字符串。这样做的结果是防止攻击者将代码中某个地方生成的签名字符串作为输入，输入到使用不同盐值生成（和验证）签名的另一段代码中。

与你的 SECRET_KEY 不同，你的盐参数不需要保密。

验证时间戳值

TimestampSigner is a subclass of Signer that appends a signed timestamp to the value. This allows you to confirm that a signed value was created within a specified period of time:

  1. >>> from datetime import timedelta
  2. >>> from django.core.signing import TimestampSigner
  3. >>> signer = TimestampSigner()
  4. >>> value = signer.sign("hello")
  5. >>> value
  6. 'hello:1NMg5H:oPVuCqlJWmChm1rA2lyTUtelC-c'
  7. >>> signer.unsign(value)
  8. 'hello'
  9. >>> signer.unsign(value, max_age=10)
  10. SignatureExpired: Signature age 15.5289158821 > 10 seconds
  11. >>> signer.unsign(value, max_age=20)
  12. 'hello'
  13. >>> signer.unsign(value, max_age=timedelta(seconds=20))
  14. '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)

    Encode, optionally compress, append current timestamp, and sign complex data structure (e.g. list, tuple, or dictionary).

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

    Checks if signed_obj was signed less than max_age seconds ago, otherwise raises SignatureExpired. The max_age parameter can accept an integer or a datetime.timedelta object.

4.2 版后已移除: Support for passing positional arguments is deprecated.

保护复杂的数据结构

If you wish to protect a list, tuple or dictionary you can do so using the Signer.sign_object() and unsign_object() methods, or signing module’s dumps() or loads() functions (which are shortcuts for TimestampSigner(salt='django.core.signing').sign_object()/unsign_object()). These use JSON serialization under the hood. JSON ensures that even if your SECRET_KEY is stolen an attacker will not be able to execute arbitrary commands by exploiting the pickle format:

  1. >>> from django.core import signing
  2. >>> signer = signing.TimestampSigner()
  3. >>> value = signer.sign_object({"foo": "bar"})
  4. >>> value
  5. 'eyJmb28iOiJiYXIifQ:1kx6R3:D4qGKiptAqo5QW9iv4eNLc6xl4RwiFfes6oOcYhkYnc'
  6. >>> signer.unsign_object(value)
  7. {'foo': 'bar'}
  8. >>> value = signing.dumps({"foo": "bar"})
  9. >>> value
  10. 'eyJmb28iOiJiYXIifQ:1kx6Rf:LBB39RQmME-SRvilheUe5EmPYRbuDBgQp2tCAi7KGLk'
  11. >>> signing.loads(value)
  12. {'foo': 'bar'}

Because of the nature of JSON (there is no native distinction between lists and tuples) if you pass in a tuple, you will get a list from signing.loads(object):

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

dumps(obj, key=None, salt=’django.core.signing’, serializer=JSONSerializer, compress=False)

返回 URL 安全的，经过签名的 base64 压缩 JSON 字符串。使用 TimestampSigner 对序列化对象进行签名。

loads(string, key=None, salt=’django.core.signing’, serializer=JSONSerializer, max_age=None, fallback_keys=None)

与 dumps() 相反，如果签名失败引发 BadSignature。如果给定，则检查 max_age （以秒为单位）。