算法¶

JWS、JWE、JWK 和 JWT 所有可用的算法。

本文档描述了在 JSON Web Signature (JWS)、JSON Web Encryption (JWE) 和 JSON Web Key (JWK) 中使用的算法。

JSON Web Key¶

JSON Web Key（JWK）的算法包括：

OctKey ：接受以比特为单位的密钥大小，这意味着 key_size 必须是 8 的倍数。
RSAKey ：接受以比特为单位的密钥大小，key_size 必须 >=512 且为 8 的倍数。
ECKey ：接受 crv 为 P-256、P-384、P-521 和 secp256k1。
OKPKey ：接受 crv 为 Ed25519、Ed448、X25519 和 X448。

JSON Web Signature¶

joserfc.jws 模块支持 RFC7518、RFC8037 和 RFC8812 中的算法。您必须为每个算法指定正确的密钥类型。

算法名	密钥类型	是推荐
none	OctKey	否
HS256	OctKey	是
HS384	OctKey	否
HS512	OctKey	否
RS256	RSAKey	是
RS384	RSAKey	否
RS512	RSAKey	否
ES256	ECKey	是
ES384	ECKey	否
ES512	ECKey	否
PS256	RSAKey	否
PS384	RSAKey	否
PS512	RSAKey	否
EdDSA	OKPKey	否
ES256K	ECKey	否

备注

EdDSA 算法只接受具有 "crv" 为 "Ed25519" 和 "Ed448" 的 OKPKey。

JSON Web Encryption¶

joserfc.jwe 模块支持 RFC7518 中的算法，以及 ECDH-1PU 的草案。您必须为每个算法指定正确的密钥类型。

算法名	密钥类型	是推荐
dir	OctKey	是
A128KW	OctKey	是
A192KW	OctKey	否
A256KW	OctKey	是
RSA1_5	RSAKey	否
RSA-OAEP	RSAKey	是
RSA-OAEP-256	RSAKey	否
ECDH-ES	ECKey	是
ECDH-ES+A128KW	ECKey	是
ECDH-ES+A192KW	ECKey	否
ECDH-ES+A256KW	ECKey	是
A128GCMKW	OctKey	否
A192GCMKW	OctKey	否
A256GCMKW	OctKey	否
PBES2-HS256+A128KW	RSAKey	否
PBES2-HS384+A192KW	RSAKey	否
PBES2-HS512+A256KW	RSAKey	否

RFC7518 中定义的所有用于 "enc" 值的算法都是推荐使用的，包括：

A128CBC-HS256
A192CBC-HS384
A256CBC-HS512
A128GCM
A192GCM
A256GCM

RFC7518 还定义了用于 "zip"（压缩）头参数的 DEF 算法，该算法推荐使用。

草案版本中还有针对 "alg" 和 "enc" 的额外算法。请参考以下章节获取更多信息。

OKPKey¶

对于以下算法，您可以使用 OKPKey 并将 "crv"（曲线）参数设置为 X25519 或 X448：

ECDH-ES
ECDH-ES+A128KW
ECDH-ES+A192KW
ECDH-ES+A256KW

This allows you to utilize these elliptic curve algorithms with OKPKey for your cryptographic operations.

C20P 与 XC20P¶

C20P 和 XC20P 算法仍处于草案阶段，默认状态下他们未注册到 JWERegistry。要使用 C20P 和 XC20P，开发人员必须安装 PyCryptodome 模块。

pip install pycryptodome

这是由于 cryptography 库只支持 "ChaCha20" 密码算法，不支持 XChaCha20，而 pycryptodome 同时支持 "ChaCha20" 和 "XChaCha20" 密码算法。

注册密码算法¶

默认的注册表不包含草案算法，开发人员必须先注册 C20P 和 XC20P：

from joserfc.drafts.jwe_chacha20 import register_chaha20_poly1305

register_chaha20_poly1305()

自定义注册表 `registry`¶

在 encrypt_compact()、decrypt_compact()、encrypt_json() 和 decrypt_json() 中使用自定义 registry。

from joserfc import jwe
from joserfc.jwk import OctKey

registry = jwe.JWERegistry(
    # add more "alg" and "enc" if you want
    algorithms=["A128KW", "C20P"]
)

key = OctKey.generate_key(128)  # A128KW requires 128 bits key
protected = {"alg": "A128KW", "enc": "C20P"}
encrypted_text = jwe.encrypt_compact(
    protected,
    b"hello",
    public_key=key,
    registry=registry,
)

ECDH-1PU 相关算法¶

椭圆曲线迪菲-赫尔曼一次通用模型（ECDH-1PU）密钥协商仍然处于草案阶段，默认情况下未注册。要使用与 ECDH-1PU 相关的算法，开发人员必须手动注册它们：

from joserfc.drafts.jwe_ecdh_1pu import register_ecdh_1pu

register_ecdh_1pu()

然后使用带有所需的 ECDH-1PU 算法的自定义 registry。例如：

from joserfc import jwe
from joserfc.jwk import ECKey

registry = jwe.JWERegistry(
    algorithms=["ECDH-1PU+A128KW", "A128CBC-HS256"]
)
protected = {"alg": "ECDH-1PU+A128KW", "enc": "A128CBC-HS256"}
recipient_key = ECKey.import_key("your-ec-public-key.json")
sender_key = ECKey.import_key("your-ec-sender-key.json")  # this SHOULD be a private key
encrypted_text = jwe.encrypt_compact(
    protected,
    b"hello",
    public_key=recipient_key,
    registry=registry,
    sender_key=sender_key,
)

重要

ECDH-1PU 算法需要一个 发送方密钥，在调用 encrypt_compact() 和 encrypt_json() 方法时，该密钥必须是私钥。

sender_key 可以是 KeySet，JWE 会根据 skid 头部值查找正确的密钥。

算法¶

JSON Web Key¶

JSON Web Signature¶

JSON Web Encryption¶

OKPKey¶

C20P 与 XC20P¶

注册密码算法¶

自定义注册表 registry¶

ECDH-1PU 相关算法¶

自定义注册表 `registry`¶