siyuan-note/siyuan · error

Invalid key backup file

Error message

Invalid key backup file

What it means

ImportNotebookCryptoBackup returns Conf.Language(317) ('invalid key backup file') at line 324 when json.Unmarshal of the provided bytes into a NotebookCrypto struct fails. The file is not valid JSON or its top-level structure does not match the NotebookCrypto schema. This is the first structural gate in the import validation chain.

Source

Thrown at kernel/model/crypto.go:324

// 安全：备份文件不含主密码（salt 不保密、verifier 是密文），导入只恢复配置，解锁仍需主密码。
// 防呆：本机已有完整且已启用的加密配置时拒绝导入，避免覆盖现有 salt/verifier 孤立现有 WrappedDEK。
// ImportNotebookCryptoBackup 接收用户导入的密钥备份文件内容（JSON 字节）+ 主密码，
// 校验主密码能解开备份里的 verifier 后才写回配置。防止 crafted 备份设置弱 KDFParams 等攻击。
// RecoveryRequired 状态允许导入，但候选 KEK 必须能解开所有现存笔记本和已删除笔记本历史。
func ImportNotebookCryptoBackup(data []byte, password string) error {
	notebookCryptoMu.Lock()
	defer notebookCryptoMu.Unlock()

	Conf.m.RLock()
	current := *Conf.NotebookCrypto
	Conf.m.RUnlock()
	if current.Enabled && notebookCryptoConfigurationComplete(&current) {
		return errors.New(Conf.Language(324))
	}

	nc := &conf.NotebookCrypto{}
	if err := json.Unmarshal(data, nc); err != nil {
		return errors.New(Conf.Language(317))
	}
	if !notebookCryptoConfigurationComplete(nc) {
		return errors.New(Conf.Language(317))
	}

	// 用导入的 salt + 用户输入的主密码派生 KEK，校验能否解开备份里的 verifier
	params, validErr := util.ValidateArgon2Params(nc.KDFParams)
	if validErr != nil {
		return errors.New(Conf.Language(317))
	}
	kek := util.DeriveKey(password, nc.MasterSalt, params)
	defer zeroAndClear(kek)
	if nc.Checksum != computeBackupChecksum(nc) {
		return errors.New(Conf.Language(317))
	}
	if !verifyKEKMAC(nc, kek) {
		return errors.New(Conf.Language(317))
	}

View on GitHub (pinned to 251596fc0d)

Solutions

1. Re-export a fresh backup from the source device's encryption settings and import that file.
2. Verify the file is the notebook-crypto-backup-*.json produced by ExportNotebookCryptoBackup, not another JSON file.
3. If migrating across versions, ensure both source and target run compatible SiYuan versions sharing the same NotebookCrypto schema.

// Reject non-JSON or non-NotebookCrypto content before importing.
var probe map[string]any
if err := json.Unmarshal(data, &probe); err != nil {
    return errors.New("file is not valid JSON")
}

When it happens

Trigger: ImportNotebookCryptoBackup is called with bytes that are not valid JSON, are truncated, or do not deserialize into conf.NotebookCrypto (missing required JSON fields, wrong types). User selects a non-backup file, a partially downloaded/corrupted backup, or a file from an incompatible version.

Common situations: User picks the wrong file (e.g., conf.json, a regular notebook .sy); backup file truncated during copy/download; backup produced by a future/newer spec the current build cannot parse; file edited externally and broken.

Related errors

• Cannot import a key backup while encrypted notebooks are ena
• Incorrect master password
• Decryption failed: incorrect key or corrupted data
• invalid import token
• no file found

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