算法

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 中的算法。您必须为每个算法指定正确的密钥类型。

算法名	密钥类型	Requirements
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。

默认情况下，JWS 的 serialize 和 deserialize 方法仅允许使用推荐算法。要使用非推荐算法，开发者必须通过 algorithms 参数或 registry 参数显式指定算法。

from joserfc import jws
from joserfc.jwk import OctKey

key = OctKey.import_key("secret")
# HS384 is a non-recommended algorithm
jws.serialize_compact({"alg": "HS384"}, b"payload", key, algorithms=["HS384"])

# or with a custom registry
registry = jws.JWSRegistry(algorithms=["HS384"])
jws.serialize_compact({"alg": "HS384"}, b"payload", key, registry=registry)

警告

none 算法已被弃用，详见 https://datatracker.ietf.org/doc/draft-ietf-jose-deprecate-none-rsa15/

JSON Web Encryption

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

算法名	密钥类型	Requirements
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

警告

RSA1_5 算法已被弃用，详见 https://datatracker.ietf.org/doc/draft-ietf-jose-deprecate-none-rsa15/

对于 "zip"（压缩）头部参数，也有一个 DEF 算法，使用 DEF 是可选的。

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

OKPKey

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

• ECDH-ES

• ECDH-ES+A128KW

• ECDH-ES+A192KW

• ECDH-ES+A256KW

这允许你在加密操作中使用 OKPKey 来利用这些椭圆曲线算法。

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_chacha20_poly1305

register_chacha20_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 头部值查找正确的密钥。