siyuan-note/siyuan · error

Argon2id KeyLength must be 32

Error message

Argon2id KeyLength must be 32

What it means

Raised by ValidateArgon2Params when p.KeyLength != 32. SiYuan's AES-256-GCM envelope (Encrypt/Decrypt and the wrapped-DEK scheme) requires a 32-byte derived key, so any other KeyLength is rejected to prevent a downstream 'requires a 32-byte (AES-256) key' failure or, worse, a silently truncated key.

Source

Thrown at kernel/util/kdf.go:65

	Parallelism uint8  `json:"parallelism"` // 并行线程数
	KeyLength   uint32 `json:"keyLength"`   // 输出密钥长度，单位字节
}

// DefaultArgon2Params 返回 OWASP 2023 推荐的 Argon2id 参数。
func DefaultArgon2Params() Argon2Params {
	return Argon2Params{
		Memory:      64 * 1024,
		Iterations:  3,
		Parallelism: 4,
		KeyLength:   32,
	}
}

// ValidateArgon2Params 校验 Argon2id 参数是否在合理范围内，防止恶意备份设置极大内存导致 OOM，
// 或过弱参数降低安全性。
func ValidateArgon2Params(p Argon2Params) (Argon2Params, error) {
	if p.KeyLength != 32 {
		return p, errors.New("Argon2id KeyLength must be 32")
	}
	if p.Memory < 64*1024 {
		return p, errors.New("Argon2id Memory too low (minimum 64 MB)")
	}
	if p.Memory > 256*1024 {
		return p, errors.New("Argon2id Memory too high (maximum 256 MB)")
	}
	if p.Iterations < 3 {
		return p, errors.New("Argon2id Iterations too low (minimum 3)")
	}
	if p.Iterations > 10 {
		return p, errors.New("Argon2id Iterations too high (maximum 10)")
	}
	if p.Parallelism == 0 || p.Parallelism > 16 {
		return p, errors.New("Argon2id Parallelism must be between 1 and 16")
	}
	return p, nil
}

View on GitHub (pinned to 251596fc0d)

Solutions

1. Reset KDFParams.KeyLength to 32 in the notebook crypto config (DefaultArgon2Params already sets it).
2. If the config is from an external/modified backup, regenerate crypto params via the official change-password flow rather than editing JSON.
3. Validate the struct with ValidateArgon2Params immediately after deserializing, so the bad value is caught at load time.

Example fix

// before
params := util.Argon2Params{Memory: 64 * 1024, Iterations: 3, Parallelism: 4, KeyLength: 16}

// after: AES-256 requires a 32-byte key
params := util.DefaultArgon2Params() // KeyLength: 32

params := util.DefaultArgon2Params() // guarantees KeyLength == 32
if _, err := util.ValidateArgon2Params(params); err != nil {
    return err
}

When it happens

Trigger: A notebook crypto config (KDFParams) is loaded from a backup or hand-edited JSON with keyLength set to something other than 32; ValidateArgon2Params is called during unlock/setup/change-password (crypto.go, crypto_lifecycle.go) and returns this error before any key derivation.

Common situations: Restoring a backup whose JSON was edited and keyLength was changed; a third-party tool writing notebook crypto metadata with a wrong field; a corrupted conf where the field defaulted to 0.

Related errors

• Argon2id Memory too low (minimum 64 MB)
• Argon2id Memory too high (maximum 256 MB)
• Argon2id Iterations too low (minimum 3)
• Argon2id Iterations too high (maximum 10)
• Argon2id Parallelism must be between 1 and 16

AI-assisted analysis of siyuan-note/siyuan@251596fc0d (2026-08-12). Data as JSON: /api/errors/5c79639a22a39629. Report an issue: GitHub.