シリアル化インターフェース—その危険なドキュメント

シリアル化インターフェース

署名インターフェースはバイトにのみ署名します。 他のタイプに署名するために、SerializerクラスはPythonのjsonモジュールと同様のdumps / loadsインターフェースを提供します。このインターフェースは、オブジェクトを文字列にシリアル化してから、 。

dumps()を使用して、データをシリアル化して署名します。

from itsdangerous.serializer import Serializer
s = Serializer("secret-key")
s.dumps([1, 2, 3, 4])
b'[1, 2, 3, 4].r7R9RhGgDPvvWl3iNzLuIIfELmo'

loads()を使用して署名を検証し、データを逆シリアル化します。

s.loads('[1, 2, 3, 4].r7R9RhGgDPvvWl3iNzLuIIfELmo')
[1, 2, 3, 4]

デフォルトでは、データは組み込みのjsonモジュールを使用してJSONにシリアル化されます。 この内部シリアライザーは、サブクラス化することで変更できます。

署名の経過時間を記録して検証するには、タイムスタンプによる署名を参照してください。 URLで安全に使用できる形式にシリアル化するには、 URL Safe Serialization を参照してください。

失敗への対応

例外には、署名チェックが失敗した場合にペイロードを検査できる便利な属性があります。 この時点で誰かがあなたのデータを改ざんしていることがわかっているので、これは特に注意して行う必要がありますが、デバッグの目的には役立つ可能性があります。

from itsdangerous.serializer import Serializer
from itsdangerous.exc import BadSignature, BadData

s = URLSafeSerializer("secret-key")
decoded_payload = None

try:
    decoded_payload = s.loads(data)
    # This payload is decoded and safe
except BadSignature as e:
    if e.payload is not None:
        try:
            decoded_payload = s.load_payload(e.payload)
        except BadData:
            pass
        # This payload is decoded but unsafe because someone
        # tampered with the signature. The decode (load_payload)
        # step is explicit because it might be unsafe to unserialize
        # the payload (think pickle instead of json!)

属性を調べて何が正確に間違っているのかを突き止めたくない場合は、loads_unsafe()を使用することもできます。

sig_okay, payload = s.loads_unsafe(data)

返されるタプルの最初の項目は、署名が正しいかどうかを示すブール値です。

フォールバック署名者

既存のシグニチャをすぐに無効にせずに、シグニチャパラメータをアップグレードすることをお勧めします。 たとえば、別のダイジェスト方法を使用することを決定できます。 新しい署名は新しい方法を使用する必要がありますが、古い署名は引き続き検証する必要があります。

現在の署名者との署名解除が失敗した場合に試行されるfallback_signersのリストを指定できます。 リストの各項目は次のとおりです。

• シリアライザーに渡されるsignerクラスをインスタンス化するためのsigner_kwargsのdict。
• secret_key、salt、およびsigner_kwargsがシリアライザーに渡されてインスタンス化されるSignerクラス。
• 指定された引数を使用して指定されたクラスをインスタンス化するための(signer_class, signer_kwargs)のタプル。

たとえば、これはSHA-512を使用して署名するシリアライザーですが、SHA-512またはSHA-1のいずれかを使用して署名を解除します。

s = Serializer(
    signer_kwargs={"digest_method": hashlib.sha512},
    fallback_signers=[{"digest_method": hashlib.sha1}]
)