Skip to content

An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作

15.2 KB
Raw Blame
// SiYuan - https://github.com/siyuan-note/siyuan
// Copyright (c) 2020-present, b3log.org
// SPDX-License-Identifier: AGPL-3.0-or-later

package crypto

import (
	"bytes"
	"crypto/ecdh"
	"crypto/ecdsa"
	"crypto/ed25519"
	"crypto/elliptic"
	"encoding/base64"
	"encoding/json"
	"fmt"

	jose "github.com/go-jose/go-jose/v4"
)

// JWK 的 kty 取值。
const (
	jwkKeyTypeOct = "oct"
	jwkKeyTypeOKP = "OKP"
)

// JWK 的 crv 取值,用于 OKP 类型的密钥。
const (
	jwkCurveEd25519 = "Ed25519"
	jwkCurveX25519  = "X25519"
)

// jsonWebKey 是 JWK 的通用视图:非对称密钥材料交由 go-jose 处理,
// 此处负责 Web Crypto 关心的元数据(kty、alg、ext、key_ops)与对称、OKP 密钥材料。
type jsonWebKey struct {
	Kty string  `json:"kty,omitempty"`
	Crv string  `json:"crv,omitempty"`
	Alg string  `json:"alg,omitempty"`
	Use *string `json:"use,omitempty"` // nil 表示成员缺失,空串同样参与校验

	// 导入时 nil 表示成员缺失,空切片表示空数组;导出时始终输出该成员。
	KeyOps []string `json:"key_ops"`
	Ext    *bool    `json:"ext,omitempty"`

	K string `json:"k,omitempty"` // 对称密钥材料
	X string `json:"x,omitempty"` // OKP 与 EC 的公钥材料
	D string `json:"d,omitempty"` // 私钥材料

	raw []byte // 原始 JSON,RSA 与 EC 的密钥材料交由 go-jose 解析
}

// importJWK 从 JWK 导入密钥。
func importJWK(alg Algorithm, data []byte, extractable bool, usages []KeyUsage) (*Key, error) {
	var jwk jsonWebKey
	if err := json.Unmarshal(data, &jwk); err != nil {
		return nil, dataError("invalid JSON Web Key: %s", err)
	}
	jwk.raw = data
	if jwk.Kty == "" {
		return nil, dataError("JSON Web Key is missing the kty member")
	}
	if err := checkJWKMetadata(&jwk, alg.Name, extractable, usages); err != nil {
		return nil, err
	}

	key, err := importJWKMaterial(&jwk, alg, extractable, usages)
	if err != nil {
		return nil, err
	}

	// alg 需要密钥位长才能确定,因此在密钥构造完成后校验。
	if jwk.Alg != "" {
		expected := jwkAlgorithm(key)
		if expected != "" && jwk.Alg != expected {
			return nil, dataError("JSON Web Key alg %q does not match %s", jwk.Alg, alg.Name)
		}
	}
	return key, nil
}

// importJWKMaterial 按算法解析 JWK 的密钥材料。
func importJWKMaterial(jwk *jsonWebKey, alg Algorithm, extractable bool, usages []KeyUsage) (*Key, error) {
	switch alg.Name {
	case AlgAESCBC, AlgAESCTR, AlgAESGCM, AlgAESKW, AlgAESECB:
		secret, err := decodeJWKOct(jwk, alg.Name)
		if err != nil {
			return nil, err
		}
		if err = checkUsages(alg.Name, KeyTypeSecret, usages); err != nil {
			return nil, err
		}
		return importAESKey(alg, secret, extractable, usages)
	case AlgHMAC:
		secret, err := decodeJWKOct(jwk, alg.Name)
		if err != nil {
			return nil, err
		}
		if err = checkUsages(alg.Name, KeyTypeSecret, usages); err != nil {
			return nil, err
		}
		return importHMACKey(alg, secret, extractable, usages)
	case AlgEd25519, AlgX25519:
		return importJWKOKP(jwk, alg, extractable, usages)
	case AlgRSASSAPKCS1, AlgRSAPSS, AlgRSAOAEP, AlgECDSA, AlgECDH:
		return importJWKAsymmetric(jwk, alg, extractable, usages)
	default:
		return nil, notSupportedError("%s keys cannot be imported from the jwk format", alg.Name)
	}
}

// importJWKOKP 解析 OKP 类型的 JWK。go-jose 不支持 X25519,因此两种曲线都在此处理。
func importJWKOKP(jwk *jsonWebKey, alg Algorithm, extractable bool, usages []KeyUsage) (*Key, error) {
	if jwk.Kty != jwkKeyTypeOKP {
		return nil, dataError("%s keys require a JSON Web Key with kty %q, got %q",
			alg.Name, jwkKeyTypeOKP, jwk.Kty)
	}

	expectedCurve := jwkCurveEd25519
	if alg.Name == AlgX25519 {
		expectedCurve = jwkCurveX25519
	}
	if jwk.Crv != expectedCurve {
		return nil, dataError("%s keys require crv %q, got %q", alg.Name, expectedCurve, jwk.Crv)
	}
	if jwk.X == "" {
		return nil, dataError("JSON Web Key is missing the x member")
	}

	public, err := decodeBase64URL(jwk.X, "x")
	if err != nil {
		return nil, err
	}

	// 含 d 成员的是私钥,否则是公钥。
	if jwk.D == "" {
		if alg.Name == AlgX25519 {
			return importX25519Raw(alg, public, extractable, usages)
		}
		return importEd25519Raw(alg, public, extractable, usages)
	}

	private, err := decodeBase64URL(jwk.D, "d")
	if err != nil {
		return nil, err
	}
	if err = checkUsages(alg.Name, KeyTypePrivate, usages); err != nil {
		return nil, err
	}

	key := &Key{
		Type:        KeyTypePrivate,
		Extractable: extractable,
		Usages:      cloneUsages(usages),
		Algorithm:   KeyAlgorithm{Name: alg.Name},
	}

	if alg.Name == AlgX25519 {
		privateKey, newErr := ecdh.X25519().NewPrivateKey(private)
		if newErr != nil {
			return nil, dataError("invalid X25519 private key: %s", newErr)
		}
		// 校验 d 与 x 是否对应同一密钥。
		if !bytes.Equal(privateKey.PublicKey().Bytes(), public) {
			return nil, dataError("the X25519 private key does not match the public key")
		}
		key.private = privateKey
		return key, nil
	}

	if len(private) != ed25519.SeedSize {
		return nil, dataError("Ed25519 private key data must be %d bytes, got %d",
			ed25519.SeedSize, len(private))
	}
	privateKey := ed25519.NewKeyFromSeed(private)
	if !bytes.Equal(privateKey.Public().(ed25519.PublicKey), public) {
		return nil, dataError("the Ed25519 private key does not match the public key")
	}
	key.private = privateKey
	return key, nil
}

// importJWKAsymmetric 借助 go-jose 解析 RSA 与 EC 的 JWK 密钥材料。
func importJWKAsymmetric(jwk *jsonWebKey, alg Algorithm, extractable bool, usages []KeyUsage) (*Key, error) {
	// go-jose 会校验坐标长度、点是否在曲线上,并对 RSA 私钥执行 Validate,
	// 并按是否含 d 成员返回私钥或公钥类型的材料。
	var parsed jose.JSONWebKey
	if err := parsed.UnmarshalJSON(jwk.raw); err != nil {
		return nil, dataError("invalid JSON Web Key: %s", err)
	}

	material := parsed.Key
	if privateKey, ok := material.(*ecdsa.PrivateKey); ok {
		checked, err := checkECPrivateKey(privateKey)
		if err != nil {
			return nil, err
		}
		material = checked
	}
	return keyFromMaterial(alg, material, extractable, usages)
}

// checkECPrivateKey 校验 EC 私钥的 d 位于 [1, n-1] 内,且其对应的公钥正是 x 与 y 给出的点,
// 返回由 d 重新推导的私钥。go-jose 只校验各成员的长度以及该点是否在曲线上,
// 而 d 与 x、y 不对应的私钥签出的签名无法用该公钥验证。
func checkECPrivateKey(privateKey *ecdsa.PrivateKey) (*ecdsa.PrivateKey, error) {
	size := (privateKey.Curve.Params().N.BitLen() + 7) / 8
	d := privateKey.D.Bytes()
	if len(d) > size {
		return nil, dataError("the EC private key is out of range")
	}

	// ParseRawPrivateKey 要求定长输入,并拒绝 0 与不小于曲线阶的值。
	derived, err := ecdsa.ParseRawPrivateKey(privateKey.Curve, append(make([]byte, size-len(d)), d...))
	if err != nil {
		return nil, dataError("invalid EC private key: %s", err)
	}
	if !derived.PublicKey.Equal(&privateKey.PublicKey) {
		return nil, dataError("the EC private key does not match the public key")
	}
	return derived, nil
}

// exportJWK 将密钥导出为 JWK。
func exportJWK(key *Key) ([]byte, error) {
	// 规范要求把 key_ops 设为密钥的用法,没有用法的密钥也要输出空数组。
	jwk := jsonWebKey{Ext: &key.Extractable, Alg: jwkAlgorithm(key), KeyOps: make([]string, 0, len(key.Usages))}
	for _, usage := range key.Usages {
		jwk.KeyOps = append(jwk.KeyOps, string(usage))
	}

	switch key.Algorithm.Name {
	case AlgAESCBC, AlgAESCTR, AlgAESGCM, AlgAESKW, AlgAESECB, AlgHMAC:
		jwk.Kty = jwkKeyTypeOct
		jwk.K = base64.RawURLEncoding.EncodeToString(key.secret)
		return json.Marshal(jwk)

	case AlgEd25519, AlgX25519:
		if err := exportJWKOKP(key, &jwk); err != nil {
			return nil, err
		}
		return json.Marshal(jwk)

	case AlgRSASSAPKCS1, AlgRSAPSS, AlgRSAOAEP, AlgECDSA, AlgECDH:
		return exportJWKAsymmetric(key, &jwk)

	default:
		return nil, notSupportedError("%s keys cannot be exported in the jwk format", key.Algorithm.Name)
	}
}

// exportJWKOKP 导出 Ed25519 与 X25519 的 JWK 密钥材料。
func exportJWKOKP(key *Key, jwk *jsonWebKey) error {
	jwk.Kty = jwkKeyTypeOKP
	jwk.Crv = jwkCurveEd25519
	if key.Algorithm.Name == AlgX25519 {
		jwk.Crv = jwkCurveX25519
	}

	switch material := key.private.(type) {
	case ed25519.PrivateKey:
		jwk.D = base64.RawURLEncoding.EncodeToString(material.Seed())
		jwk.X = base64.RawURLEncoding.EncodeToString(material.Public().(ed25519.PublicKey))
		return nil
	case *ecdh.PrivateKey:
		jwk.D = base64.RawURLEncoding.EncodeToString(material.Bytes())
		jwk.X = base64.RawURLEncoding.EncodeToString(material.PublicKey().Bytes())
		return nil
	}

	switch material := key.public.(type) {
	case ed25519.PublicKey:
		jwk.X = base64.RawURLEncoding.EncodeToString(material)
		return nil
	case *ecdh.PublicKey:
		jwk.X = base64.RawURLEncoding.EncodeToString(material.Bytes())
		return nil
	default:
		return operationError("the key does not hold %s key material", key.Algorithm.Name)
	}
}

// exportJWKAsymmetric 借助 go-jose 导出 RSA 与 EC 的密钥材料,再合并 Web Crypto 的元数据。
func exportJWKAsymmetric(key *Key, jwk *jsonWebKey) ([]byte, error) {
	material := key.public
	if key.Type == KeyTypePrivate {
		material = key.private
	}

	// ECDH 的密钥在内核中以 ecdh 类型保存,go-jose 只认 ecdsa 类型。
	converted, err := ecdsaMaterialOf(material)
	if err != nil {
		return nil, err
	}

	encoded, err := (&jose.JSONWebKey{Key: converted}).MarshalJSON()
	if err != nil {
		return nil, operationError("failed to encode the JSON Web Key: %s", err)
	}

	// 将 go-jose 输出的密钥材料与 Web Crypto 的元数据合并到同一个对象。
	var merged map[string]any
	if err = json.Unmarshal(encoded, &merged); err != nil {
		return nil, operationError("failed to decode the JSON Web Key: %s", err)
	}
	// go-jose 不输出这些成员,由 Web Crypto 规范决定其取值。
	delete(merged, "use")
	delete(merged, "kid")
	if jwk.Alg != "" {
		merged["alg"] = jwk.Alg
	}
	merged["key_ops"] = jwk.KeyOps
	merged["ext"] = key.Extractable

	return json.Marshal(merged)
}

// checkJWKMetadata 校验 JWK 的 ext、key_ops 与 use 成员是否与导入参数相符。
func checkJWKMetadata(jwk *jsonWebKey, algName string, extractable bool, usages []KeyUsage) error {
	if jwk.Ext != nil && !*jwk.Ext && extractable {
		return dataError("JSON Web Key is marked as non-extractable")
	}

	// key_ops 只要存在就参与校验,空数组不允许任何用法;RFC 7517 不允许其中出现重复值。
	if jwk.KeyOps != nil {
		allowed := make([]KeyUsage, 0, len(jwk.KeyOps))
		for _, op := range jwk.KeyOps {
			if containsUsage(allowed, KeyUsage(op)) {
				return dataError("JSON Web Key key_ops contains the duplicate value %q", op)
			}
			allowed = append(allowed, KeyUsage(op))
		}
		for _, usage := range usages {
			if !containsUsage(allowed, usage) {
				return dataError("JSON Web Key key_ops does not allow %s", usage)
			}
		}
	}

	// 规范按算法确定 use 的取值,并且只在请求了用法时校验。
	if jwk.Use != nil && len(usages) > 0 {
		if expected := jwkUse(algName); expected != "" && *jwk.Use != expected {
			return dataError("JSON Web Key use %q does not match %s, which requires %q", *jwk.Use, algName, expected)
		}
	}
	return nil
}

// jwkUse 返回算法要求的 JWK use 取值:签名算法为 sig,加密、包装与密钥协商算法为 enc。
func jwkUse(algName string) string {
	switch algName {
	case AlgHMAC, AlgRSASSAPKCS1, AlgRSAPSS, AlgECDSA, AlgEd25519:
		return "sig"
	case AlgAESCBC, AlgAESCTR, AlgAESGCM, AlgAESKW, AlgAESECB, AlgRSAOAEP, AlgECDH, AlgX25519:
		return "enc"
	default:
		return ""
	}
}

// decodeJWKOct 解析对称密钥的 k 成员。
func decodeJWKOct(jwk *jsonWebKey, algName string) ([]byte, error) {
	if jwk.Kty != jwkKeyTypeOct {
		return nil, dataError("%s keys require a JSON Web Key with kty %q, got %q", algName, jwkKeyTypeOct, jwk.Kty)
	}
	if jwk.K == "" {
		return nil, dataError("JSON Web Key is missing the k member")
	}

	secret, err := decodeBase64URL(jwk.K, "k")
	if err != nil {
		return nil, err
	}
	return secret, nil
}

// decodeBase64URL 解析 JWK 中的 base64url 成员,不接受填充字符。
func decodeBase64URL(value string, member string) ([]byte, error) {
	ret, err := base64.RawURLEncoding.DecodeString(value)
	if err != nil {
		return nil, dataError("JSON Web Key %s member is not valid base64url: %s", member, err)
	}
	return ret, nil
}

// ecdsaMaterialOf 将内核保存的密钥材料转换为 go-jose 可编码的类型。
// crypto/ecdh 的密钥需要转换为 crypto/ecdsa 的等价表示。
func ecdsaMaterialOf(material any) (any, error) {
	switch typed := material.(type) {
	case *ecdh.PrivateKey:
		curve, err := ellipticCurveOf(typed.Curve())
		if err != nil {
			return nil, err
		}
		privateKey, err := ecdsa.ParseRawPrivateKey(curve, typed.Bytes())
		if err != nil {
			return nil, operationError("failed to convert the ECDH private key: %s", err)
		}
		return privateKey, nil
	case *ecdh.PublicKey:
		curve, err := ellipticCurveOf(typed.Curve())
		if err != nil {
			return nil, err
		}
		publicKey, err := ecdsa.ParseUncompressedPublicKey(curve, typed.Bytes())
		if err != nil {
			return nil, operationError("failed to convert the ECDH public key: %s", err)
		}
		return publicKey, nil
	default:
		return material, nil
	}
}

// ellipticCurveOf 返回 ecdh 曲线对应的 elliptic 曲线。
func ellipticCurveOf(curve ecdh.Curve) (elliptic.Curve, error) {
	for _, info := range curves {
		if info.ECDH == curve {
			return info.Curve, nil
		}
	}
	return nil, notSupportedError("the key uses a curve that cannot be encoded as a JSON Web Key")
}

// jwkAlgorithm 返回密钥对应的 JWK alg 取值,无对应取值时返回空串。
func jwkAlgorithm(key *Key) string {
	switch key.Algorithm.Name {
	case AlgAESCBC, AlgAESCTR, AlgAESGCM, AlgAESKW:
		if key.Algorithm.Length == nil {
			return ""
		}
		suffix := map[string]string{
			AlgAESCBC: "CBC",
			AlgAESCTR: "CTR",
			AlgAESGCM: "GCM",
			AlgAESKW:  "KW",
		}[key.Algorithm.Name]
		return fmt.Sprintf("A%d%s", *key.Algorithm.Length, suffix)
	case AlgRSASSAPKCS1:
		return jwkHashSuffix("RS", key.Algorithm.Hash)
	case AlgRSAPSS:
		return jwkHashSuffix("PS", key.Algorithm.Hash)
	case AlgRSAOAEP:
		switch key.Algorithm.Hash {
		case AlgSHA1:
			return "RSA-OAEP"
		case AlgSHA256:
			return "RSA-OAEP-256"
		case AlgSHA384:
			return "RSA-OAEP-384"
		case AlgSHA512:
			return "RSA-OAEP-512"
		default:
			return ""
		}
	case AlgECDSA:
		switch key.Algorithm.NamedCurve {
		case CurveP256:
			return "ES256"
		case CurveP384:
			return "ES384"
		case CurveP521:
			return "ES512"
		default:
			return ""
		}
	case AlgECDH, AlgX25519, AlgEd25519:
		// 规范未为这些算法定义 alg 取值。
		return ""
	case AlgAESECB:
		// AES-ECB 不是 Web Crypto 算法,JWA 注册表也没有对应的 alg 取值,
		// 因此不输出该成员,避免伪造出看似已注册的名称。
		return ""
	case AlgHMAC:
		return jwkHashSuffix("HS", key.Algorithm.Hash)
	default:
		return ""
	}
}

// jwkHashSuffix 按摘要算法拼接 alg 取值,例如 RS256。SHA-1 的后缀为 1。
func jwkHashSuffix(prefix string, hashName string) string {
	switch hashName {
	case AlgSHA1:
		return prefix + "1"
	case AlgSHA256:
		return prefix + "256"
	case AlgSHA384:
		return prefix + "384"
	case AlgSHA512:
		return prefix + "512"
	default:
		return ""
	}
}