An open-source, privacy-first, self-hosted knowledge workspace where humans and AI agents work together 开源、隐私优先、自托管的知识工作空间,让人与智能体在此协作
TypeScript agentic-aiai-agentknowledge-baselocal-firstmarkdownmcpmindmapnote-takingself-hostedsiyuanworkspace
// SiYuan - https://github.com/siyuan-note/siyuan
// Copyright (c) 2020-present, b3log.org
// SPDX-License-Identifier: AGPL-3.0-or-later
package model
import (
"bytes"
"crypto/hmac"
"crypto/rand"
"crypto/sha256"
"encoding/binary"
"encoding/hex"
"encoding/json"
"errors"
"fmt"
"io"
"io/fs"
"net/url"
"os"
"path/filepath"
"sort"
"strings"
"sync"
"sync/atomic"
"time"
"github.com/88250/gulu"
"github.com/88250/lute/ast"
"github.com/siyuan-note/filelock"
"github.com/siyuan-note/logging"
"github.com/siyuan-note/siyuan/kernel/av"
"github.com/siyuan-note/siyuan/kernel/cache"
"github.com/siyuan-note/siyuan/kernel/conf"
"github.com/siyuan-note/siyuan/kernel/filesys"
"github.com/siyuan-note/siyuan/kernel/heif"
"github.com/siyuan-note/siyuan/kernel/sql"
"github.com/siyuan-note/siyuan/kernel/treenode"
"github.com/siyuan-note/siyuan/kernel/util"
)
// kekVerifierMagic 是写入 KEKVerifier 的固定魔数。启用时用 KEK 加密它,校验主密码时解密比对。
var kekVerifierMagic = []byte("siyuan-encrypted-notebook")
const boxEncryptionSpec = 1
var encryptedAssetMagic = []byte{'S', 'Y', 'A', 'E'}
var errEncryptedNotebookPayloadFound = errors.New("encrypted notebook payload found")
// runtimeEncryptedBoxes 记录当前工作空间进程内已确认的加密笔记本身份,避免同步或外部删除配置后降级为普通笔记本。
// value 为确认身份时的 DataDir,防止测试或切换工作空间时复用其他工作空间的运行时状态。
var runtimeEncryptedBoxes sync.Map // map[string]string
// runtimeNormalBoxes 缓存已确认的普通笔记本,减少普通笔记本高频访问时的文件系统探测。
var runtimeNormalBoxes sync.Map // map[string]string
// IsEncryptedNotebookData 判断数据是否以当前文档或资源密文标识开头。
func IsEncryptedNotebookData(data []byte) bool {
return util.IsCiphertext(data) || bytes.HasPrefix(data, encryptedAssetMagic)
}
func markRuntimeEncryptedBox(boxID string) {
if ast.IsNodeIDPattern(boxID) {
forgetRuntimeNormalBox(boxID)
runtimeEncryptedBoxes.Store(boxID, filepath.Clean(util.DataDir))
}
}
func forgetRuntimeEncryptedBox(boxID string) {
dataDir, ok := runtimeEncryptedBoxes.Load(boxID)
if ok && dataDir == filepath.Clean(util.DataDir) {
runtimeEncryptedBoxes.Delete(boxID)
}
forgetRuntimeNormalBox(boxID)
}
func isRuntimeEncryptedBox(boxID string) bool {
dataDir, ok := runtimeEncryptedBoxes.Load(boxID)
return ok && dataDir == filepath.Clean(util.DataDir)
}
func markRuntimeNormalBox(boxID string) {
if ast.IsNodeIDPattern(boxID) {
runtimeNormalBoxes.Store(boxID, filepath.Clean(util.DataDir))
}
}
func forgetRuntimeNormalBox(boxID string) {
dataDir, ok := runtimeNormalBoxes.Load(boxID)
if ok && dataDir == filepath.Clean(util.DataDir) {
runtimeNormalBoxes.Delete(boxID)
}
}
func isRuntimeNormalBox(boxID string) bool {
dataDir, ok := runtimeNormalBoxes.Load(boxID)
return ok && dataDir == filepath.Clean(util.DataDir)
}
// hasEncryptedNotebookPayload 在密钥身份文件缺失或损坏时检查磁盘密文标识,防止自动修复为普通笔记本。
func hasEncryptedNotebookPayload(boxID string) (bool, error) {
if !ast.IsNodeIDPattern(boxID) {
return false, errors.New("invalid notebook ID")
}
return hasEncryptedNotebookPayloadAtPath(filepath.Join(util.DataDir, boxID))
}
func hasEncryptedNotebookPayloadAtPath(boxDir string) (bool, error) {
if !filelock.IsExist(boxDir) {
return false, nil
}
err := filepath.WalkDir(boxDir, func(path string, entry fs.DirEntry, walkErr error) error {
if walkErr != nil {
return walkErr
}
if entry.IsDir() || entry.Type()&os.ModeType != 0 {
return nil
}
file, openErr := os.Open(path)
if openErr != nil {
return openErr
}
var header [4]byte
n, readErr := io.ReadFull(file, header[:])
closeErr := file.Close()
if readErr != nil && readErr != io.EOF && readErr != io.ErrUnexpectedEOF {
return readErr
}
if closeErr != nil {
return closeErr
}
if IsEncryptedNotebookData(header[:n]) {
return errEncryptedNotebookPayloadFound
}
return nil
})
if errors.Is(err, errEncryptedNotebookPayloadFound) {
return true, nil
}
return false, err
}
const encryptedAssetMetadataMaxSize = 1024 * 1024
const encryptedAssetLegacySpec = 1
const encryptedAssetSpec = 2
const encryptedAssetContainerIDSize = 32
const encryptedAssetChunkSize = 1024 * 1024
const encryptedAssetChunkMaxCiphertextSize = encryptedAssetChunkSize + 1024
type encryptedAssetMetadata struct {
Spec int `json:"spec"`
ContainerID []byte `json:"containerID"`
OriginalName string `json:"originalName"`
Size int64 `json:"size"`
Chunks uint64 `json:"chunks"`
}
// errMasterPasswordMigrationPending 表示改密已切换全局 verifier,但部分笔记本配置尚待恢复。
var errMasterPasswordMigrationPending = errors.New("master password migration is pending")
// notebookCryptoMu 串行化加密笔记本的控制面操作(Enable/Disable/Create/ChangeMasterPassword/Import/restore 等),
// 避免 ChangeMasterPassword 枚举与 CreateEncryptedBox 并发导致新笔记本用旧 KEK 但 verifier 已切换的不可恢复状态。
var notebookCryptoMu sync.Mutex
var masterPasswordMigrationMu sync.Mutex
// boxLifecycleLocks 为每个 box 提供一个 RWMutex,协调锁定操作与在途解密请求。
// 在途解密请求持读锁,LockBox 持写锁,确保锁定后不会有新的解密输出。
var boxLifecycleLocks = sync.Map{} // map[string]*sync.RWMutex
func acquireBoxReadLock(boxID string) {
muI, _ := boxLifecycleLocks.LoadOrStore(boxID, &sync.RWMutex{})
muI.(*sync.RWMutex).RLock()
}
func releaseBoxReadLock(boxID string) {
if muI, ok := boxLifecycleLocks.Load(boxID); ok {
muI.(*sync.RWMutex).RUnlock()
}
}
func acquireBoxWriteLock(boxID string) {
muI, _ := boxLifecycleLocks.LoadOrStore(boxID, &sync.RWMutex{})
muI.(*sync.RWMutex).Lock()
}
func tryAcquireBoxWriteLock(boxID string) bool {
muI, _ := boxLifecycleLocks.LoadOrStore(boxID, &sync.RWMutex{})
return muI.(*sync.RWMutex).TryLock()
}
func releaseBoxWriteLock(boxID string) {
if muI, ok := boxLifecycleLocks.Load(boxID); ok {
muI.(*sync.RWMutex).Unlock()
}
}
// NotebookCryptoMuLock 锁定 notebookCryptoMu,供 api 层读取一致的状态快照。
func NotebookCryptoMuLock() { notebookCryptoMu.Lock() }
// NotebookCryptoMuUnlock 解锁 notebookCryptoMu。
func NotebookCryptoMuUnlock() { notebookCryptoMu.Unlock() }
// dataCryptoBackupPath 是全局 NotebookCrypto 的备份路径,位于 DataDir/.siyuan/ 下(进入 dejavu 同步范围)。
// MasterSalt 是加密体系的全局根基:conf/conf.json 丢失后若重新启用会生成新 salt,
// 导致旧 WrappedDEK 无法用相同主密码解开(KEK 随 salt 改变)。把整套 NotebookCrypto 备份到
// 同步目录,conf.json 丢失时通过同步恢复或本地备份即可重新解锁已有加密笔记本。
// MasterSalt/KEKVerifier 设计为可明文(salt 不保密,verifier 是密文),备份文件按明文 JSON 存储。
func dataCryptoBackupPath() string {
return filepath.Join(util.DataDir, ".siyuan", "data-crypto-backup.json")
}
// notebookCryptoAuthPayload 生成密钥身份认证载荷。
// AutoLockMinutes 是本机运行策略,修改它不应使主密码和同步密钥候选失效。
func notebookCryptoAuthPayload(nc *conf.NotebookCrypto) conf.NotebookCrypto {
tmp := *nc
tmp.AutoLockMinutes = 0
return tmp
}
// computeBackupChecksum 计算 NotebookCrypto 密钥身份字段的 SHA-256 校验和。
func computeBackupChecksum(nc *conf.NotebookCrypto) string {
tmp := notebookCryptoAuthPayload(nc)
tmp.Checksum = ""
tmp.KEKMAC = nil
data, _ := json.Marshal(tmp)
h := sha256.Sum256(data)
return hex.EncodeToString(h[:])
}
// computeKEKMAC 用 KEK 计算备份的 HMAC-SHA256 认证码。
func computeKEKMAC(nc *conf.NotebookCrypto, kek []byte) []byte {
tmp := notebookCryptoAuthPayload(nc)
tmp.KEKMAC = nil
data, _ := json.Marshal(tmp)
mac := hmac.New(sha256.New, kek)
mac.Write(data)
return mac.Sum(nil)
}
// verifyKEKMAC 用 KEK 验证备份的 HMAC-SHA256 认证码。
func verifyKEKMAC(nc *conf.NotebookCrypto, kek []byte) bool {
if nc == nil || len(nc.KEKMAC) == 0 || len(kek) == 0 {
return false
}
expected := computeKEKMAC(nc, kek)
return hmac.Equal(expected, nc.KEKMAC)
}
// prepareBackupForWrite 为写入准备备份元数据字段(Spec/BackupID/CreatedAt/Checksum)。
func prepareBackupForWrite(nc *conf.NotebookCrypto) {
nc.Spec = conf.CurrentNotebookCryptoSpec
if nc.BackupID == "" {
nc.BackupID = util.RandString(16)
}
nc.CreatedAt = time.Now().Unix()
nc.Checksum = computeBackupChecksum(nc)
}
// atomicWriteFile 原子写入:先写带随机后缀的临时文件再 rename,防止半写入文件残留,
// 同时避免多个写者竞争同一固定 tmp 文件名造成 lost update。
func atomicWriteFile(path string, data []byte) error {
tmpPath := path + "." + gulu.Rand.String(7) + ".tmp"
if err := os.WriteFile(tmpPath, data, 0644); err != nil {
return err
}
return os.Rename(tmpPath, path)
}
// ExportNotebookCryptoBackup 把密钥备份文件复制到 export 目录,返回可下载的相对路径。
// 供用户主动导出保存,作为同步之外的独立恢复途径(详见设计文档 §4.1)。
// 备份文件本身不含主密码(salt 不保密、verifier 是密文),拿到它也解不开任何数据。
func ExportNotebookCryptoBackup() (downloadPath string, err error) {
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
backupPath := dataCryptoBackupPath()
data, readErr := filelock.ReadFile(backupPath)
if readErr != nil {
if os.IsNotExist(readErr) {
err = errors.New(Conf.Language(315))
return
}
err = readErr
return
}
exportBase := filepath.Join(util.TempDir, "export")
if mkErr := os.MkdirAll(exportBase, 0755); mkErr != nil {
err = mkErr
return
}
// 用随机名避免不同用户/设备互相覆盖,文件名固定带易识别前缀
fileName := "notebook-crypto-backup-" + gulu.Rand.String(7) + ".json"
downloadPath = "/export/" + url.PathEscape(fileName)
if writeErr := os.WriteFile(filepath.Join(exportBase, fileName), data, 0644); writeErr != nil {
err = writeErr
return
}
return
}
// ImportNotebookCryptoBackup 接收用户导入的密钥备份文件内容(JSON 字节),
// 校验为合法 NotebookCrypto 后写回 <DataDir>/.siyuan/data-crypto-backup.json 并装回本机 Conf。
// 用于新设备/重装后不依赖同步、手动恢复加密配置(详见设计文档 §4.1)。
// 安全:备份文件不含主密码(salt 不保密、verifier 是密文),导入只恢复配置,解锁仍需主密码。
// 防呆:本机已有完整且已启用的加密配置时拒绝导入,避免覆盖现有 salt/verifier 孤立现有 WrappedDEK。
// ImportNotebookCryptoBackup 接收用户导入的密钥备份文件内容(JSON 字节)+ 主密码,
// 校验主密码能解开备份里的 verifier 后才写回配置。防止 crafted 备份设置弱 KDFParams 等攻击。
// RecoveryRequired 状态允许导入,但候选 KEK 必须能解开所有现存笔记本和已删除笔记本历史。
func ImportNotebookCryptoBackup(data []byte, password string) error {
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
if err := checkPendingNotebookArchives(); err != nil {
return err
}
Conf.m.RLock()
current := *Conf.NotebookCrypto
Conf.m.RUnlock()
if current.Enabled && notebookCryptoConfigurationComplete(¤t) {
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))
}
decrypted, dErr := util.DecryptWithAAD(kek, nc.KEKVerifier, []byte("siyuan:kek-verifier"))
if dErr != nil || string(decrypted) != string(kekVerifierMagic) {
return errors.New(Conf.Language(311)) // 主密码错误
}
// 校验 KEK 能解密现存笔记本和已删除笔记本历史中的 WrappedDEK,避免导入不匹配的备份。
if !verifyKEKAgainstExistingBoxes(kek, nc) || !verifyKEKAgainstEncryptedHistory(kek, nc) {
return errors.New(Conf.Language(316)) // 密钥不匹配
}
nc.KDFParams = params // 确保写回 Conf 的参数已经通过完整校验。
nc.Enabled = true
// 先写 backup,再提交 conf;backup 失败时 conf 尚未改变,可重试
if err := writeNotebookCryptoBackupData(nc, kek); err != nil {
return fmt.Errorf("failed to persist key backup: %w", err)
}
Conf.m.Lock()
*Conf.NotebookCrypto = *nc
Conf.m.Unlock()
Conf.Save()
IncSync()
return nil
}
// saveNotebookCryptoBackup 把当前 NotebookCrypto(含 MasterSalt/KEKVerifier/KDFParams)备份到 DataDir。
// kek 必须非 nil:在 Checksum 定型后计算 KEKMAC 并落盘,保证恢复路径可通过 MAC 校验。
// 无 KEK 生成的备份 KEKMAC 必为空,会被 deriveKEK/恢复路径拒绝,等于制造无法解锁的状态(详见设计 §19)。
func saveNotebookCryptoBackup(kek []byte) error {
if kek == nil {
// 无 KEK 时不得生成当前格式备份:KEKMAC 缺失会被 deriveKEK/恢复路径拒绝,
// 生成即等于制造无法解锁的状态。
return errors.New("cannot generate notebook crypto backup without KEK")
}
Conf.m.Lock()
nc := *Conf.NotebookCrypto // 值拷贝
prepareBackupForWrite(&nc)
nc.KEKMAC = computeKEKMAC(&nc, kek)
if !notebookCryptoConfigurationComplete(&nc) {
Conf.m.Unlock()
return errors.New("cannot save incomplete notebook crypto configuration")
}
Conf.NotebookCrypto.Spec = nc.Spec
Conf.NotebookCrypto.BackupID = nc.BackupID
Conf.NotebookCrypto.CreatedAt = nc.CreatedAt
Conf.NotebookCrypto.Checksum = nc.Checksum
Conf.NotebookCrypto.KEKMAC = nc.KEKMAC // 保持 Conf 与备份文件的 KEKMAC 一致
Conf.m.Unlock()
backupPath := dataCryptoBackupPath()
if err := os.MkdirAll(filepath.Dir(backupPath), 0755); err != nil {
return fmt.Errorf("mkdir notebook crypto backup dir failed: %w", err)
}
data, err := json.Marshal(nc)
if err != nil {
return fmt.Errorf("marshal notebook crypto backup failed: %w", err)
}
if err := atomicWriteFile(backupPath, data); err != nil {
return fmt.Errorf("write notebook crypto backup failed: %w", err)
}
return nil
}
// writeNotebookCryptoBackupData 将指定的 NotebookCrypto 写入备份文件(不依赖 Conf.NotebookCrypto)。
// kek 必须非 nil:在 Checksum 定型后计算 KEKMAC,保证落盘 MAC 与落盘内容一致。
func writeNotebookCryptoBackupData(nc *conf.NotebookCrypto, kek []byte) error {
if kek == nil {
return errors.New("cannot generate notebook crypto backup without KEK")
}
prepareBackupForWrite(nc)
nc.KEKMAC = computeKEKMAC(nc, kek)
if !notebookCryptoConfigurationComplete(nc) {
return errors.New("cannot write incomplete notebook crypto backup")
}
backupPath := dataCryptoBackupPath()
if err := os.MkdirAll(filepath.Dir(backupPath), 0755); err != nil {
return fmt.Errorf("mkdir notebook crypto backup dir failed: %w", err)
}
data, err := json.Marshal(nc)
if err != nil {
return fmt.Errorf("marshal notebook crypto backup failed: %w", err)
}
if err := atomicWriteFile(backupPath, data); err != nil {
return fmt.Errorf("write notebook crypto backup failed: %w", err)
}
return nil
}
// verifyKEKAgainstExistingBoxes 用 KEK 对所有现有加密笔记本的 WrappedDEK 做无副作用解密校验。
// 优先尝试 conf 的 WrappedDEK,解密失败时 fallback 到 backup(与解锁路径一致);
// GetBoxEncryption 报错时 fail-closed(元数据损坏的加密笔记本不能静默跳过)。
// 全部通过或不存在加密笔记本时返回 true。
func verifyKEKAgainstExistingBoxes(kek []byte, nc *conf.NotebookCrypto) bool {
if nc != nil {
keys, err := decryptHistoryKEKs(kek, nc.HistoryKEKs)
clearHistoryKEKs(keys)
if err != nil {
return false
}
}
boxIDs, err := listAllEncryptedBoxIDs()
if err != nil {
logging.LogErrorf("list encrypted notebooks failed: %s", err)
return false
}
for _, id := range boxIDs {
boxCrypt, err := GetBoxEncryption(id)
if err != nil {
return false // 元数据读取失败 → fail-closed
}
if boxCrypt == nil || len(boxCrypt.WrappedDEK) == 0 {
return false // ListAllEncryptedBoxIDs 认定为加密但无可用 key material → fail-closed
}
if dek, dErr := decryptWrappedDEKWithHistory(id, boxCrypt, kek, nc); dErr == nil {
zeroAndClear(dek)
continue // 解密成功
}
// conf 的 WrappedDEK 无法解密:尝试 backup(与解锁路径 fallback 一致)
backup, bErr := readNotebookCryptBackup(id)
if bErr == nil && backup != nil && len(backup.WrappedDEK) > 0 &&
!bytes.Equal(backup.WrappedDEK, boxCrypt.WrappedDEK) {
if dek, err2 := decryptWrappedDEKWithHistory(id, backup, kek, nc); err2 == nil {
zeroAndClear(dek)
continue // backup 解密成功
}
}
return false
}
return true
}
// loadNotebookCryptoBackup 从 DataDir 读取 NotebookCrypto 备份。文件不存在返回 (nil, nil)。
func loadNotebookCryptoBackup() (*conf.NotebookCrypto, error) {
data, err := filelock.ReadFile(dataCryptoBackupPath())
if err != nil {
if os.IsNotExist(err) {
return nil, nil
}
return nil, err
}
nc := &conf.NotebookCrypto{}
if err := json.Unmarshal(data, nc); err != nil {
return nil, err
}
if nc.Spec != conf.CurrentNotebookCryptoSpec {
return nil, fmt.Errorf("unsupported notebook crypto backup spec [%d]", nc.Spec)
}
if !notebookCryptoConfigurationComplete(nc) {
return nil, errors.New("notebook crypto backup is incomplete or corrupted")
}
return nc, nil
}
// removeNotebookCryptoBackup 删除备份文件(禁用加密功能时调用)。文件不存在视为成功。
func removeNotebookCryptoBackup() {
if err := os.Remove(dataCryptoBackupPath()); err != nil && !os.IsNotExist(err) {
logging.LogErrorf("remove notebook crypto backup failed: %s", err)
}
}
// masterPasswordMigration 记录改密迁移的完整状态,用于崩溃后恢复。
type masterPasswordMigration struct {
OldVerifier []byte `json:"oldVerifier"`
NewVerifier []byte `json:"newVerifier"`
NewVerifierNonce []byte `json:"newVerifierNonce"`
NewKDFParams json.RawMessage `json:"newKDFParams"`
NewHistoryKEKs [][]byte `json:"newHistoryKEKs,omitempty"`
Boxes []migrationBoxEntry `json:"boxes"`
}
type migrationBoxEntry struct {
BoxID string `json:"boxID"`
NewSpec int `json:"newSpec"`
NewWrappedDEK []byte `json:"newWrappedDEK"`
NewWrapNonce []byte `json:"newWrapNonce"`
Metadata []byte `json:"metadata"`
}
func masterPasswordMigrationPath() string {
return filepath.Join(util.DataDir, ".siyuan", "master-password-migration.json")
}
func writeMasterPasswordMigration(m *masterPasswordMigration) error {
masterPasswordMigrationMu.Lock()
defer masterPasswordMigrationMu.Unlock()
return writeMasterPasswordMigrationUnlocked(m)
}
func writeMasterPasswordMigrationUnlocked(m *masterPasswordMigration) error {
p := masterPasswordMigrationPath()
if err := os.MkdirAll(filepath.Dir(p), 0755); err != nil {
return fmt.Errorf("mkdir master password migration dir failed: %w", err)
}
data, err := gulu.JSON.MarshalIndentJSON(m, "", " ")
if err != nil {
return fmt.Errorf("marshal master password migration failed: %w", err)
}
return filelock.WriteFile(p, data)
}
func readMasterPasswordMigration() (*masterPasswordMigration, error) {
masterPasswordMigrationMu.Lock()
defer masterPasswordMigrationMu.Unlock()
return readMasterPasswordMigrationUnlocked()
}
func readMasterPasswordMigrationUnlocked() (*masterPasswordMigration, error) {
p := masterPasswordMigrationPath()
if !filelock.IsExist(p) {
return nil, nil
}
data, err := filelock.ReadFile(p)
if err != nil {
return nil, fmt.Errorf("read master password migration failed: %w", err)
}
var m masterPasswordMigration
if err = gulu.JSON.UnmarshalJSON(data, &m); err != nil {
return nil, fmt.Errorf("unmarshal master password migration failed: %w", err)
}
return &m, nil
}
func removeMasterPasswordMigration() {
masterPasswordMigrationMu.Lock()
defer masterPasswordMigrationMu.Unlock()
removeMasterPasswordMigrationUnlocked()
}
func removeMasterPasswordMigrationUnlocked() {
p := masterPasswordMigrationPath()
if err := filelock.Remove(p); err != nil && !os.IsNotExist(err) {
logging.LogErrorf("remove master password migration failed: %s", err)
}
}
func removeMasterPasswordMigrationBox(boxID string) {
if boxID == "" {
return
}
masterPasswordMigrationMu.Lock()
defer masterPasswordMigrationMu.Unlock()
mig, err := readMasterPasswordMigrationUnlocked()
if err != nil || mig == nil {
return
}
remaining := make([]migrationBoxEntry, 0, len(mig.Boxes))
found := false
for _, entry := range mig.Boxes {
if entry.BoxID == boxID {
found = true
continue
}
remaining = append(remaining, entry)
}
if !found {
return
}
if len(remaining) == 0 && len(mig.NewHistoryKEKs) == 0 {
removeMasterPasswordMigrationUnlocked()
return
}
mig.Boxes = remaining
if err = writeMasterPasswordMigrationUnlocked(mig); err != nil {
logging.LogErrorf("remove notebook [%s] from master password migration failed: %s", boxID, err)
}
}
// MasterPasswordMigrationStatus 返回是否存在待完成的改密迁移及受影响的笔记本。
func MasterPasswordMigrationStatus() (pending bool, boxIDs []string) {
mig, err := readMasterPasswordMigration()
if err != nil || mig == nil {
return false, nil
}
for _, entry := range mig.Boxes {
boxIDs = append(boxIDs, entry.BoxID)
}
return true, boxIDs
}
// recoverMasterPasswordMigration 在启动时检测并完成中断的改密迁移。
// 若 migration manifest 存在,根据全局 verifier 是否已切换决定恢复策略。
func recoverMasterPasswordMigration() {
mig, err := readMasterPasswordMigration()
if err != nil {
logging.LogErrorf("read master password migration failed: %s", err)
return
}
if mig == nil {
return // 无待恢复的迁移
}
remaining := make([]migrationBoxEntry, 0, len(mig.Boxes))
pendingRecovery := false
for _, entry := range mig.Boxes {
if !ast.IsNodeIDPattern(entry.BoxID) {
logging.LogWarnf("drop invalid notebook [%s] from master password migration", entry.BoxID)
continue
}
if !filelock.IsExist(filepath.Join(util.DataDir, entry.BoxID)) {
deleted, historyErr := hasEncryptedNotebookDeleteHistory(entry.BoxID)
if historyErr != nil {
logging.LogWarnf("keep missing notebook [%s] in master password migration because delete history check failed: %s", entry.BoxID, historyErr)
remaining = append(remaining, entry)
pendingRecovery = true
continue
}
if deleted {
logging.LogInfof("drop deleted notebook [%s] from master password migration", entry.BoxID)
continue
}
logging.LogWarnf("keep missing notebook [%s] in master password migration until synchronization or recovery restores it", entry.BoxID)
remaining = append(remaining, entry)
pendingRecovery = true
continue
}
remaining = append(remaining, entry)
}
if pendingRecovery {
mig.Boxes = remaining
if writeErr := writeMasterPasswordMigration(mig); writeErr != nil {
logging.LogErrorf("update master password migration with pending notebook failed: %s", writeErr)
return
}
logging.LogInfof("postpone master password migration recovery until missing notebooks are restored")
return
}
if len(remaining) != len(mig.Boxes) {
mig.Boxes = remaining
if len(mig.Boxes) == 0 && len(mig.NewHistoryKEKs) == 0 {
removeMasterPasswordMigration()
return
}
if writeErr := writeMasterPasswordMigration(mig); writeErr != nil {
logging.LogErrorf("update master password migration after notebook removal failed: %s", writeErr)
return
}
}
Conf.m.RLock()
currentVerifier := Conf.NotebookCrypto.KEKVerifier
Conf.m.RUnlock()
if bytes.Equal(currentVerifier, mig.NewVerifier) {
if mig.NewHistoryKEKs != nil {
Conf.m.Lock()
Conf.NotebookCrypto.HistoryKEKs = mig.NewHistoryKEKs
Conf.m.Unlock()
}
// Phase 2 已完成(verifier 已切换),补写未完成的 box
for _, entry := range mig.Boxes {
box := &Box{ID: entry.BoxID}
boxConf := box.GetConf()
if !boxConf.Encrypted || boxConf.BoxCrypt == nil {
// conf 缺失/损坏:尝试从 per-notebook backup 重建
backup, bErr := readNotebookCryptBackup(entry.BoxID)
if bErr == nil && backup != nil && len(backup.WrappedDEK) > 0 {
boxConf = box.GetConf() // 重新获取默认 conf
boxConf.Encrypted = true
boxConf.BoxCrypt = backup
if saveErr := box.SaveConf(boxConf); saveErr != nil {
logging.LogErrorf("rebuild encrypted conf from backup [%s] failed: %s", entry.BoxID, saveErr)
return // 保留 manifest
}
} else {
// conf 与 backup 均不可用:manifest 是该 box 加密密钥的权威来源(NewWrappedDEK/NewWrapNonce/NewSpec),
// 直接从 manifest 重建 BoxCrypt,避免 conf+backup 双缺失时永久循环失败。boxConf 的非加密元数据
// (Name 等)此时已随 conf 丢失,恢复为默认值,但 box 的文档树(.sy 文件)不受影响,数据可达性得以保全。
logging.LogWarnf("rebuild encrypted box [%s] from migration manifest (conf and backup both unavailable)", entry.BoxID)
boxConf = box.GetConf()
boxConf.Encrypted = true
boxConf.BoxCrypt = &conf.BoxEncryption{
WrappedDEK: entry.NewWrappedDEK,
WrapNonce: entry.NewWrapNonce,
Spec: entry.NewSpec,
Metadata: entry.Metadata,
CreatedAt: time.Now().UnixMilli(),
}
if saveErr := box.SaveConf(boxConf); saveErr != nil {
logging.LogErrorf("rebuild encrypted conf from manifest [%s] failed: %s", entry.BoxID, saveErr)
return // 保留 manifest
}
}
}
// 若 WrappedDEK 已匹配则跳过写 conf,但仍需确保 per-notebook backup 是最新的
if bytes.Equal(boxConf.BoxCrypt.WrappedDEK, entry.NewWrappedDEK) &&
bytes.Equal(boxConf.BoxCrypt.Metadata, entry.Metadata) {
if writeErr := writeNotebookCryptBackup(entry.BoxID, boxConf.BoxCrypt); writeErr != nil {
logging.LogErrorf("refresh box crypt backup [%s] failed: %s", entry.BoxID, writeErr)
return // 保留 manifest
}
continue
}
boxConf.BoxCrypt.WrappedDEK = entry.NewWrappedDEK
boxConf.BoxCrypt.Spec = entry.NewSpec
boxConf.BoxCrypt.WrapNonce = entry.NewWrapNonce
boxConf.BoxCrypt.Metadata = append([]byte(nil), entry.Metadata...)
if saveErr := box.SaveConf(boxConf); saveErr != nil {
logging.LogErrorf("recover box conf [%s] failed: %s", entry.BoxID, saveErr)
return // 保留 manifest
}
if writeErr := writeNotebookCryptBackup(entry.BoxID, boxConf.BoxCrypt); writeErr != nil {
logging.LogErrorf("recover box crypt backup [%s] failed: %s", entry.BoxID, writeErr)
return // 保留 manifest
}
}
// 持久化全局 conf。此时没有新密码派生出的 KEK,不能为新备份生成可信 MAC,
// 因此保留迁移清单和旧备份,待用户首次输入新密码后校验全部 WrappedDEK,再完成备份切换。
Conf.Save()
logging.LogInfof("master password migration data recovered, waiting for the new password to authenticate the backup")
} else {
// Phase 2 未完成:清除 manifest,保留旧 verifier + 旧 WrappedDEK,状态一致
removeMasterPasswordMigration()
logging.LogErrorf("master password migration was interrupted, please retry")
}
}
// hasEncryptedNotebook 检查数据目录中是否存在加密笔记本,不依赖全局加密功能是否启用。
// EnableEncryptedNotebook 用它避免重新生成 MasterSalt,从而孤立旧 WrappedDEK。
func hasEncryptedNotebook() (bool, error) {
ids, err := listAllEncryptedBoxIDs()
return len(ids) > 0, err
}
// HasEncryptedNotebookHistory 检查历史目录中是否存在加密笔记本的历史快照。
// 笔记本删除后其 box 目录(含 .siyuan/conf.json 和 notebook-crypto-backup.json)会被
// 原样密文备份到历史目录(RemoveBox 的 filelock.Copy),但此时 IsEncryptedBox 已返回 false
// (box 目录已删)。因此 DisableEncryptedNotebook 不能只靠 ListAllEncryptedBoxIDs 判定——
// 已删除加密笔记本的历史仍依赖当前 MasterSalt/KEKVerifier 才能恢复,禁用并删除备份会让这些
// 历史永久锁死,违反设计 §19。本函数扫描历史目录识别这类依赖。
//
// 判定信号:历史条目 <HistoryDir>/<ts>-<op>/<boxID>/.siyuan/ 下存在
// notebook-crypto-backup.json(专为 box 删除后的恢复设计),或 conf.json 标记 Encrypted=true。
// boxID 用 ast.IsNodeIDPattern 校验,避免误判 assets/storage 等非 box 目录。
func scanEncryptedNotebookHistory() (bool, error) {
boxDirs, err := encryptedNotebookHistoryBoxDirs()
return len(boxDirs) > 0, err
}
func encryptedNotebookHistoryBoxDirs() (ret []string, err error) {
entries, err := os.ReadDir(util.HistoryDir)
if err != nil {
if os.IsNotExist(err) {
return nil, nil
}
return nil, fmt.Errorf("read history dir failed: %w", err)
}
for _, entry := range entries {
if !entry.IsDir() {
continue
}
// 历史快照目录:<ts>-<op>,其下是各 boxID 子目录
snapshotDir := filepath.Join(util.HistoryDir, entry.Name())
boxEntries, readErr := os.ReadDir(snapshotDir)
if readErr != nil {
return nil, fmt.Errorf("read history snapshot [%s] failed: %w", entry.Name(), readErr)
}
for _, boxEntry := range boxEntries {
if !boxEntry.IsDir() || !ast.IsNodeIDPattern(boxEntry.Name()) {
continue
}
encrypted, checkErr := isEncryptedHistoryBoxDir(filepath.Join(snapshotDir, boxEntry.Name()))
if checkErr != nil {
return nil, checkErr
}
if encrypted {
ret = append(ret, filepath.Join(snapshotDir, boxEntry.Name()))
}
}
}
return ret, nil
}
func hasEncryptedNotebookDeleteHistory(boxID string) (bool, error) {
if !ast.IsNodeIDPattern(boxID) {
return false, errors.New("invalid notebook ID")
}
entries, err := os.ReadDir(util.HistoryDir)
if err != nil {
if os.IsNotExist(err) {
return false, nil
}
return false, fmt.Errorf("read history dir failed: %w", err)
}
deleteSuffix := "-" + HistoryOpDelete
for _, entry := range entries {
if !entry.IsDir() || !strings.HasSuffix(entry.Name(), deleteSuffix) {
continue
}
boxDir := filepath.Join(util.HistoryDir, entry.Name(), boxID)
if !filelock.IsExist(boxDir) {
continue
}
encrypted, checkErr := isEncryptedHistoryBoxDir(boxDir)
if checkErr != nil {
return false, checkErr
}
if encrypted {
return true, nil
}
}
return false, nil
}
func verifyKEKAgainstEncryptedHistory(kek []byte, nc *conf.NotebookCrypto) bool {
boxDirs, err := encryptedNotebookHistoryBoxDirs()
if err != nil {
logging.LogErrorf("list encrypted notebook history failed: %s", err)
return false
}
for _, boxDir := range boxDirs {
boxID := filepath.Base(boxDir)
candidates, readErr := readEncryptedHistoryBoxEncryptionCandidates(boxDir)
if readErr != nil {
logging.LogErrorf("read encrypted notebook history [%s] failed: %s", boxID, readErr)
return false
}
matched := false
for _, candidate := range candidates {
dek, decryptErr := decryptWrappedDEKWithHistory(boxID, candidate, kek, nc)
if decryptErr == nil {
zeroAndClear(dek)
matched = true
break
}
}
if !matched {
return false
}
}
return true
}
func readEncryptedHistoryBoxEncryptionCandidates(boxDir string) (ret []*conf.BoxEncryption, err error) {
var candidateErrors []error
backupPath := filepath.Join(boxDir, ".siyuan", "notebook-crypto-backup.json")
if filelock.IsExist(backupPath) {
if candidate, readErr := readBoxEncryptionFile(backupPath); readErr == nil {
ret = append(ret, candidate)
} else {
candidateErrors = append(candidateErrors, readErr)
}
}
confPath := filepath.Join(boxDir, ".siyuan", "conf.json")
if filelock.IsExist(confPath) {
data, readErr := filelock.ReadFile(confPath)
if readErr != nil {
candidateErrors = append(candidateErrors, readErr)
} else {
boxConf := conf.NewBoxConf()
if readErr = gulu.JSON.UnmarshalJSON(data, boxConf); readErr != nil {
candidateErrors = append(candidateErrors, readErr)
} else if boxConf.Encrypted && boxConf.BoxCrypt != nil {
if readErr = validateBoxEncryption(boxConf.BoxCrypt); readErr != nil {
candidateErrors = append(candidateErrors, readErr)
} else {
ret = append(ret, boxConf.BoxCrypt)
}
}
}
}
if len(ret) > 0 {
return ret, nil
}
if len(candidateErrors) > 0 {
return nil, errors.Join(candidateErrors...)
}
return nil, errors.New("encrypted notebook history has no valid key material")
}
// HasEncryptedNotebookHistory 在扫描失败时按存在依赖处理,避免调用方因 I/O 或权限错误删除恢复材料。
func HasEncryptedNotebookHistory() bool {
hasHistory, err := scanEncryptedNotebookHistory()
if err != nil {
logging.LogErrorf("scan encrypted notebook history failed: %s", err)
return true
}
return hasHistory
}
// isEncryptedHistoryBoxDir 判断历史目录中的 boxID 子目录是否属于加密笔记本。
// 优先看 notebook-crypto-backup.json(删除前随 box 目录整体备份,是加密身份的权威标识),
// 再 fallback 到 conf.json 的 Encrypted 标志。
func isEncryptedHistoryBoxDir(boxDir string) (bool, error) {
siyuanDir := filepath.Join(boxDir, ".siyuan")
backupPath := filepath.Join(siyuanDir, "notebook-crypto-backup.json")
if _, err := os.Stat(backupPath); err == nil {
return true, nil
} else if !os.IsNotExist(err) {
return false, fmt.Errorf("stat encrypted notebook history backup [%s] failed: %w", boxDir, err)
}
confPath := filepath.Join(siyuanDir, "conf.json")
if _, err := os.Stat(confPath); err != nil {
if os.IsNotExist(err) {
return false, nil
}
return false, fmt.Errorf("stat encrypted notebook history conf [%s] failed: %w", boxDir, err)
}
data, err := filelock.ReadFile(confPath)
if err != nil {
return false, fmt.Errorf("read encrypted notebook history conf [%s] failed: %w", boxDir, err)
}
var boxConf conf.BoxConf
if err = gulu.JSON.UnmarshalJSON(data, &boxConf); err != nil {
return false, fmt.Errorf("parse encrypted notebook history conf [%s] failed: %w", boxDir, err)
}
return boxConf.Encrypted, nil
}
// cachedDEKs 缓存已解锁加密笔记本的 DEK,按 boxID 索引。
// KEK 不全局缓存("严格每笔记本单独解锁"语义):UnlockBox 临时派生 KEK 解出 DEK 后即丢弃 KEK,
// 仅保留 per-box DEK 供后续读写加解密。
var (
cachedDEKs = map[string][]byte{}
cachedDEKsLock sync.RWMutex
)
// boxLastAccess 记录每个加密笔记本最近一次真实用户交互或显式保活时间(unix 纳秒),供自动锁定 cron 使用。
// key: boxID, value: *atomic.Int64。UnlockBox 成功时初始化,Unmount 时清理。
var boxLastAccess sync.Map
// EnableEncryptedNotebookWithSync 在启用前先完成同步;同步恢复了既有配置时只校验原主密码。
func EnableEncryptedNotebookWithSync(password string) error {
if len(password) == 0 {
return errors.New("password must not be empty")
}
if err := SyncDataBeforeEnableEncryptedNotebook(); err != nil {
return err
}
// 同步准备需独占写接口;完成同步后再为密钥配置操作取得导入读租约。
dataImportAccess.RLock()
defer dataImportAccess.RUnlock()
if err := checkDataImportRecovery(); err != nil {
return err
}
// 同步可能已经从其他设备恢复了完整配置。此时校验用户输入的是原主密码,不能再创建新的密钥体系。
if NotebookCryptoEnabled() {
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
kek, err := deriveKEK(password)
if kek != nil {
zeroAndClear(kek)
}
return err
}
return EnableEncryptedNotebook(password)
}
// EnableEncryptedNotebook 启用加密笔记本功能:生成 MasterSalt、派生 KEK、写入校验值并持久化。
// 重复调用(已启用)返回错误,避免覆盖现有加密笔记本的密钥参数。
// KEK 不缓存——启用后用户需对每个加密笔记本单独调 UnlockBox 解锁。
func EnableEncryptedNotebook(password string) error {
if len(password) == 0 {
return errors.New("password must not be empty")
}
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
if err := checkPendingNotebookArchives(); err != nil {
return err
}
Conf.m.RLock()
current := *Conf.NotebookCrypto
Conf.m.RUnlock()
if current.Enabled && notebookCryptoConfigurationComplete(¤t) {
return errors.New(Conf.Language(312))
}
hasEncrypted, listErr := hasEncryptedNotebook()
if listErr != nil {
return fmt.Errorf("list encrypted notebooks failed: %w", listErr)
}
hasHistory, historyErr := scanEncryptedNotebookHistory()
if historyErr != nil {
return fmt.Errorf("check encrypted notebook history failed: %w", historyErr)
}
hasBackup := filelock.IsExist(dataCryptoBackupPath())
if hasEncrypted || hasHistory || hasBackup {
// 现存笔记本、已删除笔记本历史或全局备份均表示已有密钥域,必须恢复并认证,不能生成新 MasterSalt。
kek, restoreErr := tryRestoreNotebookCryptoFromBackupLocked(password)
if kek != nil {
zeroAndClear(kek)
}
if restoreErr != nil {
if strings.Contains(restoreErr.Error(), Conf.Language(311)) {
return errors.New(Conf.Language(311))
}
return errors.New(Conf.Language(315))
}
logging.LogInfof("encrypted notebook re-enabled with authenticated recovery key material")
return nil
}
// 不存在任何密钥依赖或备份时生成新的 MasterSalt。
salt, err := util.GenerateSalt()
if err != nil {
return err
}
Conf.m.RLock()
kdfParams := Conf.NotebookCrypto.KDFParams
Conf.m.RUnlock()
params, validErr := util.ValidateArgon2Params(kdfParams)
if validErr != nil {
return validErr
}
kek := util.DeriveKey(password, salt, params)
defer zeroAndClear(kek)
// 用 KEK 加密固定魔数作为校验值,落盘后供后续 UnlockBox 离线校验
verifierCT, err := util.EncryptWithAAD(kek, kekVerifierMagic, []byte("siyuan:kek-verifier"))
if err != nil {
return err
}
verifierNonce, nonceErr := util.EncryptionNonce(verifierCT)
if nonceErr != nil {
return nonceErr
}
Conf.m.Lock()
previous := *Conf.NotebookCrypto
Conf.NotebookCrypto.Enabled = true
Conf.NotebookCrypto.MasterSalt = salt
Conf.NotebookCrypto.KDFParams = params
Conf.NotebookCrypto.KEKVerifier = verifierCT
Conf.NotebookCrypto.VerifierNonce = verifierNonce
Conf.m.Unlock()
// 先持久化恢复备份,再提交 conf。此时尚无加密笔记本和历史依赖,任一步失败都不会孤立既有密文。
if err := saveNotebookCryptoBackup(kek); err != nil {
// 备份写失败则恢复启用前的内存配置;conf 尚未写入,无需再执行磁盘回滚。
logging.LogErrorf("save notebook crypto backup failed: %s", err)
Conf.m.Lock()
*Conf.NotebookCrypto = previous
Conf.m.Unlock()
return fmt.Errorf("enable encrypted notebook failed: failed to persist key backup: %w", err)
}
// Conf.Save 内部会加 Conf.m,不能在持锁状态下调用(RWMutex 不可重入)。
// 即使配置写入失败,已落盘的备份仍可在下次启动时恢复同一套密钥材料。
Conf.Save()
IncSync()
return nil
}
// DisableEncryptedNotebook 关闭加密笔记本功能。前置:不能有加密笔记本存在,
// 且不能有依赖当前密钥备份的已删除笔记本历史(否则禁用并删除备份会让这些历史永久锁死,违反 §19)。
// 清除全局加密配置(MasterSalt/KEKVerifier),KEK/DEK 不再可用。
func DisableEncryptedNotebook() error {
lockSync()
defer unlockSync()
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
if err := checkPendingNotebookArchives(); err != nil {
return err
}
// 检查是否还有加密笔记本(含 conf 损坏但存在备份的)
ids, listErr := listAllEncryptedBoxIDs()
if listErr != nil {
return fmt.Errorf("list encrypted notebooks failed: %w", listErr)
}
if len(ids) > 0 {
return errors.New("cannot disable encrypted notebook feature while encrypted notebooks exist, remove them first")
}
// 检查历史目录中是否存在已删除加密笔记本的历史快照:其恢复仍依赖当前 MasterSalt/KEKVerifier,
// 删除备份前必须先清除这些历史(详见设计 §19)
hasHistory, historyErr := scanEncryptedNotebookHistory()
if historyErr != nil {
return fmt.Errorf("check encrypted notebook history failed: %w", historyErr)
}
if hasHistory {
return errors.New(Conf.Language(323))
}
if err := preserveNotebookCryptoBeforeDisable(); err != nil {
logging.LogErrorf("preserve notebook crypto before disabling failed: %s", err)
return errors.New(Conf.Language(407))
}
Conf.m.Lock()
autoLockMinutes := Conf.NotebookCrypto.AutoLockMinutes
Conf.NotebookCrypto = conf.NewNotebookCrypto()
Conf.NotebookCrypto.AutoLockMinutes = autoLockMinutes
Conf.m.Unlock()
Conf.Save()
removeNotebookCryptoBackup() // 禁用时清理备份,避免残留旧密钥材料
IncSync()
return nil
}
// restoreNotebookCryptoConfigFromBackup 把备份里的 NotebookCrypto 配置装回本机 conf.json(不需主密码)。
// 用于数据同步/导入 Data.zip 后:备份文件随 DataDir 到达新设备,但本机 conf.json 的 NotebookCrypto 还是空的。
// 此时把 salt/verifier/KDFParams 装回并置 Enabled=true,让 UI 显示"已启用",笔记本显示为锁定(解锁仍需主密码)。
// 前置:仅在本机 Enabled=false 时调用,避免覆盖正在使用的本机配置。
// 安全:salt 不保密、verifier 是密文,装回配置本身不暴露任何明文数据(解锁仍需主密码派生 KEK)。
func restoreNotebookCryptoConfigFromBackup() {
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
Conf.m.RLock()
enabled := Conf.NotebookCrypto.Enabled
Conf.m.RUnlock()
if enabled {
return // 本机已启用,不覆盖
}
backup, err := loadNotebookCryptoBackup()
if err != nil || backup == nil || len(backup.MasterSalt) == 0 || len(backup.KEKVerifier) == 0 {
return // 无可用备份,静默跳过
}
// 校验 KDFParams:非法参数时拒绝恢复
params, validErr := util.ValidateArgon2Params(backup.KDFParams)
if validErr != nil {
logging.LogErrorf("skip restore notebook crypto: invalid KDFParams in backup: %s", validErr)
return
}
backup.KDFParams = params
backup.Enabled = true
Conf.m.Lock()
*Conf.NotebookCrypto = *backup
Conf.m.Unlock()
Conf.Save()
logging.LogInfof("notebook crypto config restored from backup (auto-enable after sync/import)")
}
// tryRestoreNotebookCryptoFromBackupLocked 在本机 NotebookCrypto 未启用时,尝试从 DataDir 备份恢复。
// 数据同步到新设备后,本机 conf.json 的 NotebookCrypto 是空的(Enabled=false),但备份文件已随
// DataDir 同步过来。此时用户点加密笔记本输主密码,deriveKEK 会调本函数用主密码校验备份里的
// verifier,校验通过则装回 salt/verifier 并置 Enabled=true,让旧 WrappedDEK 可正常解开。
// 校验通过时同时返回已派生的 KEK(恢复用的 salt 与装回的 salt 相同,避免 deriveKEK 重复跑 Argon2id)。
// 返回错误表示恢复失败(备份缺失/主密码错),此时 KEK 为 nil。
func tryRestoreNotebookCryptoFromBackupLocked(password string) (kek []byte, err error) {
backup, kek, err := deriveNotebookCryptoBackupCandidate(password)
if err != nil {
return nil, err
}
params, _ := util.ValidateArgon2Params(backup.KDFParams)
backup.KDFParams = params // 确保写回 Conf 的参数已经通过完整校验。
backup.Enabled = true
Conf.m.Lock()
backup.AutoLockMinutes = Conf.NotebookCrypto.AutoLockMinutes
*Conf.NotebookCrypto = *backup
Conf.m.Unlock()
Conf.Save()
// 恢复成功后同步重写备份,确保配置和备份内容一致。
// 调用方已持有 notebookCryptoMu,且 writeNotebookCryptoBackupData 不再申请该锁,故无死锁;
// 同步写避免与 ChangeMasterPassword 的并发备份写竞争同一文件(lost update 导致 verifier 被回退)。
nc := *backup
if err := writeNotebookCryptoBackupData(&nc, kek); err != nil {
logging.LogWarnf("rewrite notebook crypto backup after restore failed: %s", err)
}
logging.LogInfof("notebook crypto restored from backup (e.g. after sync to a new device)")
return kek, nil
}
// deriveNotebookCryptoBackupCandidate 对同步备份做无副作用验证,并确认它覆盖全部现有加密笔记本。
func deriveNotebookCryptoBackupCandidate(password string) (backup *conf.NotebookCrypto, kek []byte, err error) {
backup, err = loadNotebookCryptoBackup()
if err != nil || backup == nil || len(backup.MasterSalt) == 0 || len(backup.KEKVerifier) == 0 {
return nil, nil, errors.New(Conf.Language(310))
}
params, validErr := util.ValidateArgon2Params(backup.KDFParams)
if validErr != nil {
return nil, nil, errors.New(Conf.Language(317))
}
kek = util.DeriveKey(password, backup.MasterSalt, params)
decrypted, decryptErr := util.DecryptWithAAD(kek, backup.KEKVerifier, []byte("siyuan:kek-verifier"))
if decryptErr != nil || string(decrypted) != string(kekVerifierMagic) {
zeroAndClear(kek)
return nil, nil, errors.New(Conf.Language(311))
}
if backup.Spec != conf.CurrentNotebookCryptoSpec || backup.Checksum == "" ||
len(backup.KEKMAC) == 0 || !verifyKEKMAC(backup, kek) {
zeroAndClear(kek)
return nil, nil, errors.New(Conf.Language(316))
}
if !verifyKEKAgainstExistingBoxes(kek, backup) || !verifyKEKAgainstEncryptedHistory(kek, backup) {
zeroAndClear(kek)
return nil, nil, errors.New(Conf.Language(316))
}
backup.KDFParams = params
return backup, kek, nil
}
// deriveKEK 从主密码派生 KEK 并校验。校验失败返回错误。KEK 仅在函数作用域内有效,调用方负责使用。
func deriveKEK(password string) ([]byte, error) {
if err := checkDataImportRecovery(); err != nil {
return nil, err
}
if err := checkPendingNotebookArchives(); err != nil {
return nil, err
}
Conf.m.RLock()
nc := *Conf.NotebookCrypto
Conf.m.RUnlock()
if !nc.Enabled {
// 本机未启用:可能是数据同步到新设备后本机 conf.json 还没有加密配置。
// 尝试从 DataDir 备份恢复(备份会随 DataDir 同步过来);恢复成功时直接复用其派生的 KEK。
kek, restoreErr := tryRestoreNotebookCryptoFromBackupLocked(password)
if restoreErr != nil {
return nil, restoreErr
}
return kek, nil // 恢复函数已校验过 verifier,KEK 直接可用
}
params, validErr := util.ValidateArgon2Params(nc.KDFParams)
if validErr != nil {
return nil, validErr
}
kek := util.DeriveKey(password, nc.MasterSalt, params)
decrypted, err := util.DecryptWithAAD(kek, nc.KEKVerifier, []byte("siyuan:kek-verifier"))
localPasswordValid := err == nil && string(decrypted) == string(kekVerifierMagic)
mig, migErr := readMasterPasswordMigration()
if !localPasswordValid {
zeroAndClear(kek)
// 本机没有进行中的改密事务时,允许采用随同步到达且能覆盖全部 WrappedDEK 的候选配置。
if migErr == nil && mig == nil {
backup, candidateKEK, candidateErr := deriveNotebookCryptoBackupCandidate(password)
if candidateErr == nil {
backup.Enabled = true
backup.AutoLockMinutes = nc.AutoLockMinutes
Conf.m.Lock()
*Conf.NotebookCrypto = *backup
Conf.m.Unlock()
Conf.Save()
logging.LogInfof("adopted synchronized notebook crypto configuration")
return candidateKEK, nil
}
}
return nil, errors.New(Conf.Language(311))
}
// 正常配置必须通过 KEKMAC 认证,不能把“MAC 缺失”当作兼容路径。
migrationPending := migErr == nil && mig != nil && bytes.Equal(nc.KEKVerifier, mig.NewVerifier)
if !migrationPending {
backup, backupErr := loadNotebookCryptoBackup()
backupMatchesConf := backupErr == nil && backup != nil &&
bytes.Equal(backup.MasterSalt, nc.MasterSalt) &&
bytes.Equal(backup.KEKVerifier, nc.KEKVerifier) &&
backup.KDFParams == nc.KDFParams
localAuthenticated := notebookCryptoConfigurationComplete(&nc) && verifyKEKMAC(&nc, kek)
backupAuthenticated := backupMatchesConf && backup.Spec == conf.CurrentNotebookCryptoSpec &&
backup.Checksum != "" && len(backup.KEKMAC) > 0 && verifyKEKMAC(backup, kek)
if !localAuthenticated && !backupAuthenticated {
zeroAndClear(kek)
return nil, errors.New(Conf.Language(315))
}
trusted := &nc
if !localAuthenticated {
trusted = backup
}
if !verifyKEKAgainstExistingBoxes(kek, trusted) {
zeroAndClear(kek)
return nil, errors.New(Conf.Language(315))
}
if !localAuthenticated {
backup.Enabled = true
backup.AutoLockMinutes = nc.AutoLockMinutes
Conf.m.Lock()
*Conf.NotebookCrypto = *backup
Conf.m.Unlock()
Conf.Save()
logging.LogInfof("repaired notebook crypto configuration from authenticated backup")
} else if !backupAuthenticated {
// 同步备份可能属于另一轮完整改密;只要本地配置仍与全部笔记本一致,就继续使用本地配置,
// 不覆盖候选备份,等待其余 WrappedDEK 同步完成后由新密码采用。
logging.LogWarnf("notebook crypto backup differs from usable local configuration; keeping both candidates")
}
}
if migrationPending {
// 崩溃恢复后的首次新密码验证:确认所有笔记本都已切换到新 KEK,再生成带认证的全局备份并结束迁移。
keys, keyErr := decryptHistoryKEKs(kek, nc.HistoryKEKs)
clearHistoryKEKs(keys)
if keyErr != nil || !verifyKEKAgainstExistingBoxes(kek, nil) || !verifyKEKAgainstEncryptedHistory(kek, &nc) {
zeroAndClear(kek)
return nil, errMasterPasswordMigrationPending
}
if err = finishMasterPasswordMigration(kek); err != nil {
zeroAndClear(kek)
return nil, fmt.Errorf("%w: %v", errMasterPasswordMigrationPending, err)
}
}
return kek, nil
}
// decryptBoxCrypt 用 KEK 解密 box 的 WrappedDEK。优先使用 GetBoxEncryption 的结果(conf → backup fallback),
// 若解密失败则尝试 backup 中不同的 WrappedDEK。
// 返回解密后的 DEK 和实际使用的 BoxCrypt(可能来自 backup)。
// 若 backup 被使用会自动修复 conf.json 和刷新 backup。
func decryptBoxCrypt(boxID string, kek []byte) (dek []byte, boxCrypt *conf.BoxEncryption, err error) {
if err = filesys.CheckDocumentAddressing(boxID); err != nil {
return nil, nil, err
}
boxCrypt, err = GetBoxEncryption(boxID)
if err != nil || boxCrypt == nil || len(boxCrypt.WrappedDEK) == 0 {
return nil, nil, fmt.Errorf("no encrypted key material for box [%s]", boxID)
}
nc := currentNotebookCrypto()
dek, err = decryptWrappedDEKWithHistory(boxID, boxCrypt, kek, nc)
if err == nil {
return dek, boxCrypt, nil
}
// 主 BoxCrypt 无法解密:尝试 backup 中不同的 WrappedDEK
backup, bErr := readNotebookCryptBackup(boxID)
if bErr == nil && backup != nil && len(backup.WrappedDEK) > 0 &&
!bytes.Equal(backup.WrappedDEK, boxCrypt.WrappedDEK) {
dek, err = decryptWrappedDEKWithHistory(boxID, backup, kek, nc)
if err == nil {
// backup 解密成功:修复 conf + 刷新 backup
box := &Box{ID: boxID}
boxConf := box.GetConf()
boxConf.Encrypted = true
boxConf.BoxCrypt = backup
if saveErr := box.SaveConf(boxConf); saveErr != nil {
logging.LogWarnf("fix encrypted box conf from backup [%s] failed: %s", boxID, saveErr)
}
if needWriteNotebookCryptBackup(boxID, backup) {
if writeErr := writeNotebookCryptBackup(boxID, backup); writeErr != nil {
logging.LogWarnf("refresh notebook crypt backup [%s] failed: %s", boxID, writeErr)
}
}
return dek, backup, nil
}
}
return nil, nil, fmt.Errorf("decrypt box [%s] failed: incorrect key or corrupted data", boxID)
}
// UnlockBox 用主密码派生 KEK,解出该笔记本的 DEK 并缓存。KEK 用完即弃,不全局缓存。
// 每次调用都跑一次 Argon2id(约 1 秒),严格满足"每笔记本单独解锁"语义。
func UnlockBox(boxID string, password string, boxEnc *conf.BoxEncryption) (err error) {
invalidateEncryptedPublishAccessCache()
if !ast.IsNodeIDPattern(boxID) {
return errors.New("invalid notebook ID")
}
// 全局配置锁先于笔记本生命周期锁获取(设计 §17 锁顺序约定),避免与持子系统锁后回取配置锁的路径死锁。
// notebookCryptoMu 持锁期间调用的 deriveKEK/conf 修复只申请 Conf.m/cachedDEKsLock,不回取 box 生命周期锁。
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
releaseTransition := holdEncryptedBoxTransition(boxID)
defer releaseTransition()
return unlockBoxHeld(boxID, password, boxEnc)
}
// UnlockAndMountBox 在同一个笔记本转换锁内完成解锁和挂载,挂载失败时回滚本次新建的解锁状态。
func UnlockAndMountBox(boxID, password string, boxEnc *conf.BoxEncryption) (alreadyMount bool, err error) {
invalidateEncryptedPublishAccessCache()
if !ast.IsNodeIDPattern(boxID) {
return false, errors.New("invalid notebook ID")
}
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
releaseTransition := holdEncryptedBoxTransition(boxID)
defer releaseTransition()
wasUnlocked := IsBoxUnlocked(boxID)
if err = unlockBoxHeld(boxID, password, boxEnc); err != nil {
return false, err
}
alreadyMount, err = mountBox(boxID)
if err != nil && !wasUnlocked {
lockBoxWithPreparationHeld(boxID, nil)
}
return alreadyMount, err
}
func unlockBoxHeld(boxID string, password string, boxEnc *conf.BoxEncryption) (err error) {
if err = filesys.CheckDocumentAddressing(boxID); err != nil {
return
}
if _, busy := boxLock.Load(boxID); busy {
return errors.New(Conf.language(239))
}
if boxEnc == nil || len(boxEnc.WrappedDEK) == 0 {
setEncryptedBoxState(boxID, EncryptedBoxStateError)
return errors.New("no encrypted key material for box")
}
if IsBoxUnlocked(boxID) {
if GetEncryptedBoxState(boxID) == EncryptedBoxStateError {
return errors.New(Conf.Language(316))
}
setEncryptedBoxState(boxID, EncryptedBoxStateUnlocked)
return nil
}
setEncryptedBoxState(boxID, EncryptedBoxStateUnlocking)
// 获取 box 写锁,与 LockBox/unmount0 串行化,防止并发锁/解锁导致 db/DEK 状态不一致
acquireBoxWriteLock(boxID)
finalState := EncryptedBoxStateLocked
defer func() {
releaseBoxWriteLock(boxID)
setEncryptedBoxState(boxID, finalState)
}()
kek, err := deriveKEK(password)
if err != nil {
return err
}
defer zeroAndClear(kek)
// 用 decryptBoxCrypt 统一处理解密 + backup fallback + conf 修复
dek, trustedCrypt, err := decryptBoxCrypt(boxID, kek)
if err != nil {
finalState = EncryptedBoxStateError
return errors.New(Conf.Language(316))
}
dekCached := false
defer func() {
if !dekCached {
zeroAndClear(dek)
}
}()
boxEnc = trustedCrypt
markRuntimeEncryptedBox(boxID)
metadataConf := &conf.BoxConf{Encrypted: true, BoxCrypt: boxEnc}
if err = decryptBoxMetadata(boxID, metadataConf, dek); err != nil {
finalState = EncryptedBoxStateError
return errors.New(Conf.Language(316))
}
// 持锁保护"开 db + 缓存 DEK"的原子性,避免与并发的 LockBox 导致 db/DEK 不一致
cachedDEKsLock.Lock()
if err = openEncryptedBoxIndexes(boxID, dek); err != nil {
cachedDEKsLock.Unlock()
finalState = EncryptedBoxStateError
return err
}
cachedDEKs[boxID] = dek
dekCached = true
cachedDEKsLock.Unlock()
// 初始化自动锁定访问时间戳,记录解锁时刻
newVal := &atomic.Int64{}
newVal.Store(time.Now().UnixNano())
boxLastAccess.Store(boxID, newVal)
// 修复 conf.json:若 conf 未正确标记加密状态则修正(例如从 backup 解锁后)
box := &Box{ID: boxID}
boxConf := box.GetConf()
if boxConf == nil || !boxConf.Encrypted || boxConf.BoxCrypt == nil ||
len(boxConf.BoxCrypt.WrappedDEK) == 0 ||
!bytes.Equal(boxConf.BoxCrypt.WrappedDEK, boxEnc.WrappedDEK) {
boxConf.Encrypted = true
boxConf.BoxCrypt = boxEnc
if saveErr := box.SaveConf(boxConf); saveErr != nil {
logging.LogWarnf("fix encrypted box conf [%s] failed: %s", boxID, saveErr)
}
}
// 刷新 per-notebook backup(不存在或内容不一致时),便于 conf 损坏恢复
if needWriteNotebookCryptBackup(boxID, boxEnc) {
if err = writeNotebookCryptBackup(boxID, boxEnc); err != nil {
logging.LogWarnf("write notebook crypt backup [%s] failed: %s", boxID, err)
}
}
finalState = EncryptedBoxStateUnlocked
return nil
}
// IsBoxUnlocked 返回该笔记本的 DEK 是否在内存(是否已解锁)。
func IsBoxUnlocked(boxID string) bool {
if !ast.IsNodeIDPattern(boxID) {
return false
}
cachedDEKsLock.RLock()
defer cachedDEKsLock.RUnlock()
_, ok := cachedDEKs[boxID]
return ok
}
func isBoxUnlockedForAccess(boxID string) bool {
if !IsBoxUnlocked(boxID) {
return false
}
state := GetEncryptedBoxState(boxID)
return state == EncryptedBoxStateUnlocked || state == EncryptedBoxStateLocking
}
// LockBox 清除指定笔记本的 DEK 并删除其加密 db 文件。Unmount 单个加密笔记本或手动锁定时调用。
func LockBox(boxID string) {
if !ast.IsNodeIDPattern(boxID) {
logging.LogWarnf("refuse to lock encrypted notebook with invalid ID [%s]", boxID)
return
}
lockBoxWithPreparation(boxID, nil)
}
// lockBoxWithPreparation 在关闭新操作并等待在途操作结束后执行锁定前准备,随后清除密钥和加密数据库。
func lockBoxWithPreparation(boxID string, prepare func()) {
releaseTransition := holdEncryptedBoxTransition(boxID)
defer releaseTransition()
lockBoxWithPreparationHeld(boxID, prepare)
}
func lockBoxWithPreparationHeld(boxID string, prepare func()) {
beginEncryptedBoxLock(boxID)
FlushTxQueue()
sql.FlushQueue()
if prepare != nil {
prepare()
}
acquireBoxWriteLock(boxID)
defer func() {
releaseBoxWriteLock(boxID)
setEncryptedBoxState(boxID, EncryptedBoxStateLocked)
}()
lockBoxHeld(boxID)
// 单 box 锁定时需要在写锁保护下刷新全局缓存,避免锁定与缓存读取之间出现明文窗口。
cache.ClearTreeCache()
sql.ClearCache()
cache.ClearDocsIAL()
cache.ClearBlocksIAL()
cache.ClearAVCache()
ResetVirtualBlockRefCache()
}
// lockBoxHeld 在已持有 box 写锁的前提下执行该 box 的锁定清理(不含全局缓存刷新)。
func lockBoxHeld(boxID string) {
av.ClearBlockCollectionIndex(boxID)
// 此时已排空在途操作并持有 box 写锁,可以安全清除该笔记本的明文 HEIF 预览缓存。
heif.ClearMemoryCache(boxID)
LivePhotoPreviews.Clear(boxID)
RevokeManagedEncryptedExportsForBox(boxID)
ClearRichClipboardBox(boxID)
ClearGlobalBacklinkSnapshots(boxID)
cachedDEKsLock.Lock()
if dek, ok := cachedDEKs[boxID]; ok {
zeroAndClear(dek)
delete(cachedDEKs, boxID)
}
cachedDEKsLock.Unlock()
mountedEncryptedBoxes.Delete(boxID)
// 清理自动锁定访问时间戳
boxLastAccess.Delete(boxID)
// 仅在 backup 缺失时从 conf 补写。正常流程中 CreateEncryptedBox/UnlockBox/ChangeMasterPassword
// 已刷新 backup,此处不再用未经解密验证的 BoxCrypt 覆盖已有 backup,
// 避免 conf 中的坏 WrappedDEK 覆盖有效恢复源。
if !filelock.IsExist(notebookCryptoBackupPath(boxID)) {
box := &Box{ID: boxID}
boxConf := box.GetConf()
if boxConf != nil && boxConf.Encrypted && boxConf.BoxCrypt != nil && len(boxConf.BoxCrypt.WrappedDEK) > 0 {
if err := writeNotebookCryptBackup(boxID, boxConf.BoxCrypt); err != nil {
logging.LogWarnf("write notebook crypt backup [%s] failed: %s", boxID, err)
}
}
}
sql.RemoveEncryptedDBFile(boxID)
treenode.RemoveEncryptedBlockTreeDBFile(boxID)
// 清理 repo 临时目录中该加密 box 的解密文件(diff/rollback/sync conflicts)
repoDirs := []string{
filepath.Join(util.TempDir, "repo", "diff", boxID),
filepath.Join(util.TempDir, "repo", "rollback", boxID),
}
for _, d := range repoDirs {
if rmErr := os.RemoveAll(d); rmErr != nil {
logging.LogWarnf("remove repo dir for box [%s] failed: %s", boxID, rmErr)
}
}
// sync/conflicts 路径带时间戳前缀,用通配匹配
if matches, globErr := filepath.Glob(filepath.Join(util.TempDir, "repo", "sync", "conflicts", "*", boxID)); globErr == nil {
for _, m := range matches {
if rmErr := os.RemoveAll(m); rmErr != nil {
logging.LogWarnf("remove repo sync conflict dir for box [%s] failed: %s", boxID, rmErr)
}
}
}
// 清理临时导出目录中该加密 box 的临时导出(htmlmd/html/PDF)
if rmErr := os.RemoveAll(filepath.Join(util.TempDir, "export", boxID)); rmErr != nil {
logging.LogWarnf("remove export/[%s] dir failed: %s", boxID, rmErr)
}
// 清理动态引用锚文本缓存
treenode.RemoveDynamicRefTexts(boxID)
}
// WrapNewDEK 用给定 KEK 生成随机 DEK 并包络,返回 BoxEncryption 元数据。
// KEK 由调用方临时派生(不来自全局缓存),调用方负责使用后丢弃。
// 同时返回原始 DEK,供调用方在创建场景下直接开 db 缓存,省去再次 Argon2id 派生。
func WrapNewDEK(boxID string, kek []byte) (*conf.BoxEncryption, []byte, error) {
dek, err := util.GenerateDEK()
if err != nil {
return nil, nil, err
}
wrapped, err := util.EncryptWithAAD(kek, dek, wrappedDEKAAD(boxID))
if err != nil {
return nil, nil, err
}
return &conf.BoxEncryption{
Spec: boxEncryptionSpec,
WrappedDEK: wrapped,
WrapNonce: mustEncryptionNonce(wrapped),
CreatedAt: time.Now().UnixMilli(),
}, dek, nil
}
func wrappedDEKAAD(boxID string) []byte {
return []byte("siyuan:wrapped-dek:" + boxID)
}
func decryptWrappedDEK(boxID string, enc *conf.BoxEncryption, kek []byte) ([]byte, error) {
if err := validateWrappedDEKEnvelope(enc); err != nil {
return nil, err
}
return util.DecryptWithAAD(kek, enc.WrappedDEK, wrappedDEKAAD(boxID))
}
func validateWrappedDEKEnvelope(enc *conf.BoxEncryption) error {
if enc == nil || enc.Spec != boxEncryptionSpec {
return errors.New("unsupported encrypted notebook key envelope")
}
if enc.CreatedAt <= 0 {
return errors.New("encrypted notebook key envelope creation time is missing")
}
nonce, err := util.EncryptionNonce(enc.WrappedDEK)
if err != nil {
return fmt.Errorf("invalid encrypted notebook key envelope: %w", err)
}
if !bytes.Equal(nonce, enc.WrapNonce) {
return errors.New("encrypted notebook key envelope nonce mismatch")
}
return nil
}
func validateBoxEncryption(enc *conf.BoxEncryption) error {
if err := validateWrappedDEKEnvelope(enc); err != nil {
return err
}
if _, err := util.EncryptionNonce(enc.Metadata); err != nil {
return fmt.Errorf("invalid encrypted notebook metadata envelope: %w", err)
}
return nil
}
// mustEncryptionNonce 从刚刚成功生成的密文中提取 nonce。生成密文格式错误属于内部不变量被破坏,直接终止执行。
func mustEncryptionNonce(ciphertext []byte) []byte {
nonce, err := util.EncryptionNonce(ciphertext)
if err != nil {
panic("extract encryption nonce failed: " + err.Error())
}
return nonce
}
// GetDEK 取已缓存的 DEK。返回副本,避免外部零化影响缓存。
// filesys/assets/db 加解密时调用。
func GetDEK(boxID string) ([]byte, error) {
if !ast.IsNodeIDPattern(boxID) {
return nil, errors.New("invalid notebook ID")
}
if IsEncryptedBox(boxID) && !isBoxUnlockedForAccess(boxID) {
return nil, errors.New("encrypted notebook is not accessible")
}
cachedDEKsLock.RLock()
defer cachedDEKsLock.RUnlock()
dek, ok := cachedDEKs[boxID]
if !ok {
return nil, errors.New("no DEK cached for box " + boxID)
}
ret := make([]byte, len(dek))
copy(ret, dek)
return ret, nil
}
// ClearDEK 清除指定笔记本的 DEK。Unmount 单个加密笔记本时调用。
func ClearDEK(boxID string) {
LockBox(boxID)
}
// ChangeMasterPassword 改主密码:用旧密码校验后,用新密码派生新 KEK,
// 重新加密 verifier,并把所有加密笔记本的 WrappedDEK 用新 KEK 重新包络后写回各自的 BoxConf。
//
// 使用两阶段提交确保崩溃后可恢复:
//
// Phase 0: 预计算所有新 WrappedDEK(内存)
// Phase 1: 写入 migration manifest
// Phase 2: 切换全局 verifier
// Phase 3: 写入各 box conf + backup
// Phase 4: 持久化全局备份和配置,清除 manifest
//
// 注意:必须在所有加密笔记本都已 Unmount 的状态下调用(DEK 不在内存),否则新旧 KEK 切换会让缓存与磁盘不一致。
func ChangeMasterPassword(oldPassword, newPassword string) error {
if len(newPassword) == 0 {
return errors.New("new password must not be empty")
}
// Serialize the complete multi-file change with snapshot readers and all sync modes.
// Acquire these locks before notebookCryptoMu, as sync refresh also uses that mutex.
release := lockAssetSourceChange()
defer release()
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
if err := checkPendingNotebookArchives(); err != nil {
return err
}
// 改密期间不能有已 Mount 的加密笔记本(DEK 在内存),否则新旧 KEK 切换会让缓存与磁盘不一致
cachedDEKsLock.RLock()
dekCount := len(cachedDEKs)
cachedDEKsLock.RUnlock()
if dekCount > 0 {
return errors.New("cannot change master password while encrypted notebooks are unlocked (DEKs in memory), lock them first")
}
encBoxIDs, listErr := listAllEncryptedBoxIDs()
if listErr != nil {
return fmt.Errorf("list encrypted notebooks failed: %w", listErr)
}
for _, id := range encBoxIDs {
if err := filesys.CheckDocumentAddressing(id); err != nil {
return err
}
}
oldKEK, err := deriveKEK(oldPassword)
if err != nil {
return err
}
defer zeroAndClear(oldKEK)
nc := currentNotebookCrypto()
params, validErr := util.ValidateArgon2Params(nc.KDFParams)
if validErr != nil {
return validErr
}
newKEK := util.DeriveKey(newPassword, nc.MasterSalt, params)
defer zeroAndClear(newKEK)
newHistoryKEKs, err := rewrapHistoryKEKs(oldKEK, newKEK, nc.HistoryKEKs)
if err != nil {
return err
}
newVerifier, err := util.EncryptWithAAD(newKEK, kekVerifierMagic, []byte("siyuan:kek-verifier"))
if err != nil {
return err
}
// Phase 0: 遍历所有加密笔记本(含 conf 损坏但存在备份的),预计算新 WrappedDEK(内存操作)
// 允许 entries 为空:用户可能已启用加密功能但尚未创建加密笔记本,此时仍需更新全局 verifier 和 backup。
var entries []migrationBoxEntry
for _, id := range encBoxIDs {
dek, boxCrypt, dErr := decryptBoxCrypt(id, oldKEK)
if dErr != nil {
return errors.New(Conf.Language(316) + " [box=" + id + "]")
}
newWrapped, nErr := util.EncryptWithAAD(newKEK, dek, wrappedDEKAAD(id))
zeroAndClear(dek)
if nErr != nil {
return nErr
}
entries = append(entries, migrationBoxEntry{
BoxID: id,
NewSpec: boxEncryptionSpec,
NewWrappedDEK: newWrapped,
NewWrapNonce: mustEncryptionNonce(newWrapped),
Metadata: append([]byte(nil), boxCrypt.Metadata...),
})
}
// Phase 1: 持久化 migration manifest(崩溃后 recovery 的依据)
newParamsJSON, _ := gulu.JSON.MarshalJSON(params)
mig := &masterPasswordMigration{
OldVerifier: nc.KEKVerifier,
NewVerifier: newVerifier,
NewVerifierNonce: mustEncryptionNonce(newVerifier),
NewKDFParams: newParamsJSON,
NewHistoryKEKs: newHistoryKEKs,
Boxes: entries,
}
if err = writeMasterPasswordMigration(mig); err != nil {
return err
}
// Phase 2: 切换全局 verifier
Conf.m.Lock()
Conf.NotebookCrypto.KEKVerifier = newVerifier
Conf.NotebookCrypto.VerifierNonce = mustEncryptionNonce(newVerifier)
Conf.NotebookCrypto.KDFParams = params
Conf.NotebookCrypto.HistoryKEKs = newHistoryKEKs
Conf.m.Unlock()
// Conf.Save 内部会加 Conf.m,不能在持锁状态下调用(RWMutex 不可重入)
Conf.Save()
// Phase 3: 写入各 box conf + backup
for _, entry := range entries {
box := &Box{ID: entry.BoxID}
boxConf := box.GetConf()
if !boxConf.Encrypted || boxConf.BoxCrypt == nil {
// conf 缺失/损坏:尝试从 per-notebook backup 重建
backup, bErr := readNotebookCryptBackup(entry.BoxID)
if bErr == nil && backup != nil && len(backup.WrappedDEK) > 0 {
boxConf = box.GetConf()
boxConf.Encrypted = true
boxConf.BoxCrypt = backup
if saveErr := box.SaveConf(boxConf); saveErr != nil {
return fmt.Errorf("%w: %s", errMasterPasswordMigrationPending,
fmt.Sprintf(Conf.Language(320), entry.BoxID+": rebuild encrypted conf from backup failed: "+saveErr.Error()))
}
} else {
// conf 与 backup 均不可用:manifest 是该 box 加密密钥的权威来源,直接从 entry 重建 BoxCrypt,
// 避免改密因瞬时 conf 损坏而中断(详见 recoverMasterPasswordMigration 中的对称处理)。
logging.LogWarnf("rebuild encrypted box [%s] from migration entry (conf and backup both unavailable)", entry.BoxID)
boxConf = box.GetConf()
boxConf.Encrypted = true
boxConf.BoxCrypt = &conf.BoxEncryption{
WrappedDEK: entry.NewWrappedDEK,
WrapNonce: entry.NewWrapNonce,
Spec: entry.NewSpec,
Metadata: entry.Metadata,
CreatedAt: time.Now().UnixMilli(),
}
if saveErr := box.SaveConf(boxConf); saveErr != nil {
return fmt.Errorf("%w: %s", errMasterPasswordMigrationPending,
fmt.Sprintf(Conf.Language(320), entry.BoxID+": rebuild encrypted conf from migration entry failed: "+saveErr.Error()))
}
}
}
boxConf.BoxCrypt.WrappedDEK = entry.NewWrappedDEK
boxConf.BoxCrypt.Spec = entry.NewSpec
boxConf.BoxCrypt.WrapNonce = entry.NewWrapNonce
boxConf.BoxCrypt.Metadata = append([]byte(nil), entry.Metadata...)
if err = box.SaveConf(boxConf); err != nil {
return fmt.Errorf("%w: %s", errMasterPasswordMigrationPending,
fmt.Sprintf(Conf.Language(320), entry.BoxID+": save conf failed: "+err.Error()))
}
if err = writeNotebookCryptBackup(entry.BoxID, boxConf.BoxCrypt); err != nil {
return fmt.Errorf("%w: %s", errMasterPasswordMigrationPending,
fmt.Sprintf(Conf.Language(320), entry.BoxID+": update notebook crypt backup failed: "+err.Error()))
}
}
// Phase 4: 持久化全局备份和配置,再清除 manifest,确保崩溃后可恢复。
if err = finishMasterPasswordMigration(newKEK); err != nil {
return fmt.Errorf("%w: %s", errMasterPasswordMigrationPending,
fmt.Sprintf(Conf.Language(320), err.Error()))
}
IncSync()
return nil
}
// finishMasterPasswordMigration 在备份和配置均成功落盘后清除迁移清单,写入失败时保留恢复材料。
func finishMasterPasswordMigration(kek []byte) error {
if util.ReadOnly {
return errors.New("cannot complete master password migration in read-only mode")
}
if err := saveNotebookCryptoBackup(kek); err != nil {
return err
}
err := func() error {
Conf.m.Lock()
defer Conf.m.Unlock()
data, err := Conf.marshalForSave()
if err != nil {
return err
}
if err = atomicWriteFile(filepath.Join(util.ConfDir, "conf.json"), data); err != nil {
return err
}
recordPersistedConf(data)
return nil
}()
if err != nil {
return fmt.Errorf("save notebook crypto configuration failed: %w", err)
}
removeMasterPasswordMigration()
return nil
}
// IsEncryptedBox 判断给定 boxID 是否为加密笔记本。
// 配置缺失或损坏时依次检查运行时身份、独立备份和密文标识,任何检查错误都按加密笔记本处理。
func IsEncryptedBox(boxID string) bool {
if !ast.IsNodeIDPattern(boxID) {
return false
}
if isRuntimeEncryptedBox(boxID) {
return true
}
if isRuntimeNormalBox(boxID) {
return false
}
normalConf := false
boxConfPath := filepath.Join(util.DataDir, boxID, ".siyuan", "conf.json")
if filelock.IsExist(boxConfPath) {
data, readErr := filelock.ReadFile(boxConfPath)
if readErr == nil {
boxConf := conf.NewBoxConf()
if unmarshalErr := gulu.JSON.UnmarshalJSON(data, boxConf); unmarshalErr == nil {
if boxConf.Encrypted {
markRuntimeEncryptedBox(boxID)
return true
}
normalConf = true
}
}
}
backupPath := notebookCryptoBackupPath(boxID)
if filelock.IsExist(backupPath) {
backup, err := readNotebookCryptBackup(boxID)
if err != nil {
logging.LogWarnf("failed to read notebook crypt backup for [%s]: %s", boxID, err)
forgetRuntimeNormalBox(boxID)
markRuntimeEncryptedBox(boxID)
return true
}
if backup != nil && len(backup.WrappedDEK) > 0 {
forgetRuntimeNormalBox(boxID)
markRuntimeEncryptedBox(boxID)
return true
}
}
if normalConf {
markRuntimeNormalBox(boxID)
return false
}
found, err := hasEncryptedNotebookPayload(boxID)
if err != nil {
logging.LogWarnf("failed to inspect notebook encryption identity for [%s]: %s", boxID, err)
forgetRuntimeNormalBox(boxID)
markRuntimeEncryptedBox(boxID)
return true
}
if found {
forgetRuntimeNormalBox(boxID)
markRuntimeEncryptedBox(boxID)
}
return found
}
// GetBoxEncryption 获取加密笔记本的 BoxEncryption(含 WrappedDEK)。
// 优先读 conf.json,若缺失/损坏则 fallback 到 per-notebook backup。
// 返回 nil 表示该 box 非加密;conf 标记加密但密钥材料缺失时返回明确错误。
func GetBoxEncryption(boxID string) (*conf.BoxEncryption, error) {
if !ast.IsNodeIDPattern(boxID) {
return nil, errors.New("invalid notebook ID")
}
box := &Box{ID: boxID}
boxConf := box.GetConf()
confMarkedEncrypted := boxConf != nil && boxConf.Encrypted
if confMarkedEncrypted {
markRuntimeEncryptedBox(boxID)
}
// conf 中有完整的 BoxCrypt
if confMarkedEncrypted && boxConf.BoxCrypt != nil && len(boxConf.BoxCrypt.WrappedDEK) > 0 {
return boxConf.BoxCrypt, nil
}
// fallback 到 backup
backup, err := readNotebookCryptBackup(boxID)
if err != nil {
return nil, err
}
if backup != nil && len(backup.WrappedDEK) > 0 {
markRuntimeEncryptedBox(boxID)
return backup, nil
}
// backup 也不可用
if confMarkedEncrypted || IsEncryptedBox(boxID) {
// conf 标记为加密但密钥材料缺失 → 明确错误(而非误报"未加密")
return nil, errors.New("encrypted notebook has no valid key material")
}
return nil, nil // 真正的非加密笔记本
}
// needWriteNotebookCryptBackup 检查是否需要写入/刷新 per-notebook backup。
// backup 不存在、或内容与 crypt 不一致时返回 true。
func needWriteNotebookCryptBackup(boxID string, crypt *conf.BoxEncryption) bool {
existing, err := readNotebookCryptBackup(boxID)
if err != nil || existing == nil {
return true
}
return !bytes.Equal(existing.WrappedDEK, crypt.WrappedDEK) ||
!bytes.Equal(existing.WrapNonce, crypt.WrapNonce) ||
!bytes.Equal(existing.Metadata, crypt.Metadata) ||
existing.Spec != crypt.Spec ||
existing.CreatedAt != crypt.CreatedAt
}
// DeepCopyBoxEncryption 深拷贝 BoxEncryption(含 []byte 字段),输入 nil 时返回 nil。
// 供 api 层在反序列化请求体前保存加密字段的不可变快照。
func DeepCopyBoxEncryption(src *conf.BoxEncryption) *conf.BoxEncryption {
if src == nil {
return nil
}
return &conf.BoxEncryption{
Spec: src.Spec,
WrappedDEK: append([]byte(nil), src.WrappedDEK...),
WrapNonce: append([]byte(nil), src.WrapNonce...),
Metadata: append([]byte(nil), src.Metadata...),
CreatedAt: src.CreatedAt,
}
}
// listAllEncryptedBoxIDs 直接扫描笔记本配置、密钥备份、密文标识及当前进程身份,不触发配置修复等副作用。
func listAllEncryptedBoxIDs() ([]string, error) {
ids := map[string]struct{}{}
dirs, err := os.ReadDir(util.DataDir)
if err != nil {
return nil, err
}
for _, dir := range dirs {
if !dir.IsDir() || !ast.IsNodeIDPattern(dir.Name()) {
continue
}
boxID := dir.Name()
encrypted := isRuntimeEncryptedBox(boxID)
normalConf := false
boxConfPath := filepath.Join(util.DataDir, boxID, ".siyuan", "conf.json")
if !encrypted {
data, readErr := filelock.ReadFile(boxConfPath)
if readErr == nil {
boxConf := conf.NewBoxConf()
if unmarshalErr := gulu.JSON.UnmarshalJSON(data, boxConf); unmarshalErr == nil {
encrypted = boxConf.Encrypted
normalConf = !boxConf.Encrypted
}
}
}
if !encrypted {
backup, backupErr := readNotebookCryptBackup(boxID)
if backupErr != nil {
return nil, backupErr
}
encrypted = backup != nil && len(backup.WrappedDEK) > 0
}
if !encrypted && !normalConf {
found, inspectErr := hasEncryptedNotebookPayload(boxID)
if inspectErr != nil {
return nil, inspectErr
}
encrypted = found
}
if encrypted {
markRuntimeEncryptedBox(boxID)
ids[boxID] = struct{}{}
}
}
runtimeEncryptedBoxes.Range(func(key, value any) bool {
boxID, idOK := key.(string)
dataDir, dirOK := value.(string)
if idOK && dirOK && ast.IsNodeIDPattern(boxID) && dataDir == filepath.Clean(util.DataDir) {
ids[boxID] = struct{}{}
}
return true
})
ret := make([]string, 0, len(ids))
for boxID := range ids {
ret = append(ret, boxID)
}
sort.Strings(ret)
return ret, nil
}
// ListAllEncryptedBoxIDs 返回所有可枚举的加密笔记本。扫描失败时记录错误并返回空列表;
// 涉及密钥覆盖或删除的调用方必须直接使用 listAllEncryptedBoxIDs 并处理错误。
func ListAllEncryptedBoxIDs() []string {
ids, err := listAllEncryptedBoxIDs()
if err != nil {
logging.LogErrorf("list encrypted notebooks failed: %s", err)
return nil
}
return ids
}
// IsSameCryptoBoundary 判断 srcBox 与 dstBox 是否处于同一加密边界(跨 box 操作是否安全)。
// 普通笔记本之间允许(都不加密);加密笔记本仅允许同一 box 内部操作——两个不同的加密笔记本各有独立 DEK,
// 之间互为"加密边界外",跨 box 移动/合并会用错 DEK 导致密文损坏。供 MoveDocs/Doc2Heading 等跨 box 操作校验。
func IsSameCryptoBoundary(srcBox, dstBox string) bool {
srcEnc := IsEncryptedBox(srcBox)
dstEnc := IsEncryptedBox(dstBox)
if !srcEnc && !dstEnc {
return true // 普通↔普通:允许
}
return srcEnc && dstEnc && srcBox == dstBox // 加密:仅同一 box 内允许
}
// IsBlockRefCrossingBoundary 判断从 srcBoxID 引用 defBlockID 是否跨越加密边界。
// 加密笔记本禁止跨边界块引(双向):加密笔记本的块只能引用同一加密笔记本内的块,普通 box 的块不能引用加密笔记本的块。
// 供 transaction 落库时兜底校验,防止手工输入/拖拽/粘贴/API 直调绕过前端搜索分流。
func IsBlockRefCrossingBoundary(srcBoxID, defBlockID string) bool {
if "" == defBlockID {
return false
}
if IsEncryptedBox(srcBoxID) {
// 源在加密 box:def 块必须在同一加密 box(查加密 blocktree db)
bt := treenode.GetBlockTreeInBox(defBlockID, srcBoxID)
return nil == bt || bt.BoxID != srcBoxID
}
// 源在普通 box:def 块必须在普通 box(查全局 blocktree,且其 box 非加密)
bt := treenode.GetBlockTree(defBlockID)
if nil == bt {
// 全局查不到时遍历加密笔记本查找,防止对向漏判(普通 box 引用加密笔记本块)
for _, encBoxID := range treenode.GetOpenedEncryptedBoxIDs() {
if encBT := treenode.GetBlockTreeInBox(defBlockID, encBoxID); nil != encBT {
bt = encBT
break
}
}
}
if nil == bt {
// 普通库未命中且锁定的加密 blocktree 不可查询时必须 fail-closed,否则只要知道加密块 ID,
// 就能在加密笔记本锁定后把跨边界引用写入全局明文数据库。同一事务树内的新块由调用方单独放行。
return normalBoxBlockRefCrossesBoundary(nil)
}
return normalBoxBlockRefCrossesBoundary(bt)
}
func normalBoxBlockRefCrossesBoundary(bt *treenode.BlockTree) bool {
return bt == nil || IsEncryptedBox(bt.BoxID)
}
// IsEncryptedAssetPath 判断给定 asset 绝对路径是否属于加密笔记本。
// 供 server 层在缩略图等场景判断是否需跳过密文文件的处理。
func IsEncryptedAssetPath(absPath string) bool {
boxID := util.BoxIDFromDataPath(absPath)
return boxID != "" && IsEncryptedBox(boxID)
}
// GetDEKIfUnlocked 返回已解锁加密笔记本的 DEK(副本)。
// 非加密笔记本返回 (nil, nil)——filesys 据此原样读写,对普通笔记本透明。
// 加密但未解锁(DEK 不在内存)返回 (nil, error)——filesys 的加解密函数遇 error 后拒绝读写,
// 避免加密笔记本在未解锁状态下静默以明文落盘(深度防御,见 issue #18034)。
func GetDEKIfUnlocked(boxID string) ([]byte, error) {
if boxID != "" && !ast.IsNodeIDPattern(boxID) {
return nil, errors.New("invalid notebook ID")
}
if !IsEncryptedBox(boxID) {
return nil, nil
}
repairEncryptedBoxStateFromDEK(boxID)
if !isBoxUnlockedForAccess(boxID) {
return nil, errors.New("encrypted notebook is locked, please unlock it first")
}
cachedDEKsLock.RLock()
defer cachedDEKsLock.RUnlock()
dek, ok := cachedDEKs[boxID]
if !ok {
return nil, errors.New("encrypted notebook is locked, please unlock it first")
}
ret := make([]byte, len(dek))
copy(ret, dek)
return ret, nil
}
// HoldBoxReadLock 获取 box 读锁,防止 LockBox 在持锁期间清除缓存/临时文件。
// 调用方完成解密输出后必须调 ReleaseBoxReadLock。
func HoldBoxReadLock(boxID string) {
if !IsEncryptedBox(boxID) {
acquireBoxReadLock(boxID)
return
}
lifecycle := getEncryptedBoxLifecycle(boxID)
lifecycle.lock.Lock()
for lifecycle.state == EncryptedBoxStateUnlocking {
lifecycle.condition.Wait()
}
acquireBoxReadLock(boxID)
lifecycle.lock.Unlock()
}
// ReleaseBoxReadLock 释放 HoldBoxReadLock 获取的 box 读锁。
func ReleaseBoxReadLock(boxID string) {
releaseBoxReadLock(boxID)
}
// ExtractBoxIDFromHistoryPath 从历史目录下的绝对路径反推 boxID。
// 路径形如 <HistoryDir>/<timestamp>-<op>/<boxID>/...,切出紧跟在时间戳目录后的一段。
// 若路径不在 HistoryDir 下或 boxID 非合法 ID 模式,返回空串。
func ExtractBoxIDFromHistoryPath(absPath string) string {
absPath = filepath.ToSlash(absPath)
historyDir := filepath.ToSlash(util.HistoryDir)
rel, err := filepath.Rel(historyDir, absPath)
if err != nil {
return ""
}
rel = filepath.ToSlash(rel)
if strings.HasPrefix(rel, "..") || rel == "." || rel == "" {
return ""
}
parts := strings.SplitN(rel, "/", 3)
if len(parts) < 2 {
return ""
}
// parts[0] = timestamp-op, parts[1] = boxID
boxID := parts[1]
if !ast.IsNodeIDPattern(boxID) {
return ""
}
return boxID
}
// EncryptFile 用 fileKey(DEK 派生子密钥)加密 .sy 文档字节,AAD 绑定 boxID + 稳定文件基名(不含父目录)。
// relativePath 会先经 filesys.SyAAD 提取稳定文件基名(<rootID>.sy)并校验合法性,
// 与文件系统读写共用同一 AAD 构造入口,保证加解密一致。
func EncryptFile(boxID, relativePath string, dek, plaintext []byte) ([]byte, error) {
fileKey := util.DeriveSubKey(dek, "siyuan/file")
defer zeroAndClear(fileKey)
aad, err := filesys.SyAAD(boxID, relativePath)
if err != nil {
return nil, err
}
return util.EncryptWithAAD(fileKey, plaintext, []byte(aad))
}
// DecryptFile 对应解密。
func DecryptFile(boxID, relativePath string, dek, ciphertext []byte) ([]byte, error) {
fileKey := util.DeriveSubKey(dek, "siyuan/file")
defer zeroAndClear(fileKey)
aad, err := filesys.SyAAD(boxID, relativePath)
if err != nil {
return nil, err
}
return util.DecryptWithAAD(fileKey, ciphertext, []byte(aad))
}
// EncryptAsset 生成单文件资源容器,名称元数据和内容分块分别认证加密。
func EncryptAsset(boxID, diskName, originalName string, dek, plaintext []byte) ([]byte, error) {
originalName = filepath.Base(strings.TrimSpace(originalName))
if originalName == "" || originalName == "." || strings.ContainsAny(originalName, `/\`) {
originalName = diskName
}
chunkCount := uint64((len(plaintext) + encryptedAssetChunkSize - 1) / encryptedAssetChunkSize)
if chunkCount == 0 {
chunkCount = 1
}
containerID := make([]byte, encryptedAssetContainerIDSize)
if _, err := rand.Read(containerID); err != nil {
return nil, err
}
metadata, err := json.Marshal(&encryptedAssetMetadata{
Spec: encryptedAssetSpec,
ContainerID: containerID,
OriginalName: originalName,
Size: int64(len(plaintext)),
Chunks: chunkCount,
})
if err != nil {
return nil, err
}
assetKey := util.DeriveSubKey(dek, "siyuan/asset")
defer zeroAndClear(assetKey)
aadPrefix := "siyuan:asset:" + boxID + ":assets/" + diskName
encryptedMetadata, err := util.EncryptWithAAD(assetKey, metadata, []byte(aadPrefix+":metadata"))
if err != nil {
return nil, err
}
if len(encryptedMetadata) > encryptedAssetMetadataMaxSize {
return nil, errors.New("encrypted asset metadata is too large")
}
ret := bytes.NewBuffer(make([]byte, 0, len(plaintext)+len(encryptedMetadata)+int(chunkCount)*64+12))
ret.Write(encryptedAssetMagic)
if err = binary.Write(ret, binary.BigEndian, uint32(len(encryptedMetadata))); err != nil {
return nil, err
}
ret.Write(encryptedMetadata)
for chunkIndex := uint64(0); chunkIndex < chunkCount; chunkIndex++ {
start := int(chunkIndex) * encryptedAssetChunkSize
end := min(start+encryptedAssetChunkSize, len(plaintext))
encryptedChunk, encryptErr := util.EncryptWithAAD(
assetKey,
plaintext[start:end],
encryptedAssetChunkAAD(aadPrefix, containerID, chunkIndex),
)
if encryptErr != nil {
return nil, encryptErr
}
if err = binary.Write(ret, binary.BigEndian, uint32(len(encryptedChunk))); err != nil {
return nil, err
}
ret.Write(encryptedChunk)
}
if err = binary.Write(ret, binary.BigEndian, uint32(0)); err != nil {
return nil, err
}
return ret.Bytes(), nil
}
func decryptAssetMetadata(boxID, diskName string, dek, ciphertext []byte) (metadata *encryptedAssetMetadata, contentOffset int, err error) {
if len(ciphertext) < 8 || !bytes.Equal(ciphertext[:4], encryptedAssetMagic) {
return nil, 0, errors.New("invalid encrypted asset format")
}
metadataSize := int(binary.BigEndian.Uint32(ciphertext[4:8]))
if metadataSize < 1 || metadataSize > encryptedAssetMetadataMaxSize || 8+metadataSize+4 > len(ciphertext) {
return nil, 0, errors.New("invalid encrypted asset metadata size")
}
assetKey := util.DeriveSubKey(dek, "siyuan/asset")
defer zeroAndClear(assetKey)
aadPrefix := "siyuan:asset:" + boxID + ":assets/" + diskName
plainMetadata, decryptErr := util.DecryptWithAAD(assetKey, ciphertext[8:8+metadataSize], []byte(aadPrefix+":metadata"))
if decryptErr != nil {
return nil, 0, decryptErr
}
defer zeroAndClear(plainMetadata)
if metadata, err = parseEncryptedAssetMetadata(plainMetadata); err != nil {
return nil, 0, err
}
return metadata, 8 + metadataSize, nil
}
// encryptedAssetChunkAAD 将分块绑定到本次写入的容器,阻止同名资源的不同版本互换分块。
func encryptedAssetChunkAAD(prefix string, containerID []byte, index uint64) []byte {
return fmt.Appendf(nil, "%s:content:v%d:%x:%d", prefix, encryptedAssetSpec, containerID, index)
}
func parseEncryptedAssetMetadata(data []byte) (*encryptedAssetMetadata, error) {
metadata := &encryptedAssetMetadata{}
if err := json.Unmarshal(data, metadata); err != nil {
return nil, err
}
var version struct {
Spec json.RawMessage `json:"spec"`
ContainerID json.RawMessage `json:"containerID"`
}
if err := json.Unmarshal(data, &version); err != nil {
return nil, err
}
// 仅认证元数据同时缺少两个版本字段时按旧容器读取,显式空值或不完整的新格式不能降级。
if len(version.Spec) == 0 && len(version.ContainerID) == 0 {
metadata.Spec = encryptedAssetLegacySpec
} else if metadata.Spec != encryptedAssetSpec || len(metadata.ContainerID) != encryptedAssetContainerIDSize {
return nil, errors.New("unsupported encrypted asset container version")
}
if metadata.OriginalName == "" || metadata.OriginalName == "." ||
filepath.Base(metadata.OriginalName) != metadata.OriginalName || strings.ContainsAny(metadata.OriginalName, `/\`) {
return nil, errors.New("invalid encrypted asset original name")
}
if metadata.Size < 0 {
return nil, errors.New("invalid encrypted asset content metadata")
}
chunks := uint64(metadata.Size) / encryptedAssetChunkSize
if metadata.Size%encryptedAssetChunkSize != 0 || metadata.Size == 0 {
chunks++
}
if metadata.Chunks != chunks {
return nil, errors.New("invalid encrypted asset chunk count")
}
return metadata, nil
}
// DecryptAssetWithName 解密资源内容并返回原始名称。
func DecryptAssetWithName(boxID, diskName string, dek, ciphertext []byte) (plaintext []byte, originalName string, err error) {
var output bytes.Buffer
originalName, err = DecryptAssetToWriter(boxID, diskName, dek, bytes.NewReader(ciphertext), &output)
if err != nil {
return nil, "", err
}
return output.Bytes(), originalName, nil
}
// DecryptAssetName 只解密资源的名称元数据,不处理资源内容。
func DecryptAssetName(boxID, diskName string, dek, ciphertext []byte) (originalName string, err error) {
metadata, _, err := decryptAssetMetadata(boxID, diskName, dek, ciphertext)
if err != nil {
return "", err
}
return metadata.OriginalName, nil
}
// DecryptAssetNameFromReader 从资源头部解密名称元数据,不读取资源内容。
func DecryptAssetNameFromReader(boxID, diskName string, dek []byte, reader io.Reader) (originalName string, err error) {
header := make([]byte, 8)
if _, err = io.ReadFull(reader, header); err != nil {
return "", err
}
if !bytes.Equal(header[:4], encryptedAssetMagic) {
return "", errors.New("invalid encrypted asset format")
}
metadataSize := int(binary.BigEndian.Uint32(header[4:8]))
if metadataSize < 1 || metadataSize > encryptedAssetMetadataMaxSize {
return "", errors.New("invalid encrypted asset metadata size")
}
encryptedMetadata := make([]byte, metadataSize)
if _, err = io.ReadFull(reader, encryptedMetadata); err != nil {
return "", err
}
assetKey := util.DeriveSubKey(dek, "siyuan/asset")
defer zeroAndClear(assetKey)
aadPrefix := "siyuan:asset:" + boxID + ":assets/" + diskName
plainMetadata, decryptErr := util.DecryptWithAAD(assetKey, encryptedMetadata, []byte(aadPrefix+":metadata"))
if decryptErr != nil {
return "", decryptErr
}
defer zeroAndClear(plainMetadata)
metadata, err := parseEncryptedAssetMetadata(plainMetadata)
if err != nil {
return "", err
}
return metadata.OriginalName, nil
}
// DecryptAssetToWriter 分块解密资源到 writer,避免大资源同时驻留密文和明文。
func DecryptAssetToWriter(boxID, diskName string, dek []byte, reader io.Reader, writer io.Writer) (originalName string, err error) {
header := make([]byte, 8)
if _, err = io.ReadFull(reader, header); err != nil {
return "", err
}
if !bytes.Equal(header[:4], encryptedAssetMagic) {
return "", errors.New("invalid encrypted asset format")
}
metadataSize := int(binary.BigEndian.Uint32(header[4:8]))
if metadataSize < 1 || metadataSize > encryptedAssetMetadataMaxSize {
return "", errors.New("invalid encrypted asset metadata size")
}
encryptedMetadata := make([]byte, metadataSize)
if _, err = io.ReadFull(reader, encryptedMetadata); err != nil {
return "", err
}
assetKey := util.DeriveSubKey(dek, "siyuan/asset")
defer zeroAndClear(assetKey)
aadPrefix := "siyuan:asset:" + boxID + ":assets/" + diskName
plainMetadata, decryptErr := util.DecryptWithAAD(assetKey, encryptedMetadata, []byte(aadPrefix+":metadata"))
if decryptErr != nil {
return "", decryptErr
}
defer zeroAndClear(plainMetadata)
metadata, err := parseEncryptedAssetMetadata(plainMetadata)
if err != nil {
return "", err
}
var written int64
for chunkIndex := uint64(0); chunkIndex < metadata.Chunks; chunkIndex++ {
var encryptedSize uint32
if err = binary.Read(reader, binary.BigEndian, &encryptedSize); err != nil {
return "", err
}
if encryptedSize == 0 || encryptedSize > encryptedAssetChunkMaxCiphertextSize {
return "", errors.New("invalid encrypted asset chunk size")
}
encryptedChunk := make([]byte, int(encryptedSize))
if _, err = io.ReadFull(reader, encryptedChunk); err != nil {
return "", err
}
aad := encryptedAssetChunkAAD(aadPrefix, metadata.ContainerID, chunkIndex)
if metadata.Spec == encryptedAssetLegacySpec {
aad = fmt.Appendf(nil, "%s:content:%d", aadPrefix, chunkIndex)
}
plainChunk, chunkErr := util.DecryptWithAAD(
assetKey,
encryptedChunk,
aad,
)
if chunkErr != nil {
return "", chunkErr
}
expectedSize := int64(encryptedAssetChunkSize)
if remaining := metadata.Size - written; remaining < expectedSize {
expectedSize = remaining
}
if int64(len(plainChunk)) != expectedSize {
zeroAndClear(plainChunk)
return "", errors.New("invalid encrypted asset plaintext chunk size")
}
n, writeErr := writer.Write(plainChunk)
written += int64(n)
zeroAndClear(plainChunk)
if writeErr != nil {
return "", writeErr
}
if n != len(plainChunk) {
return "", io.ErrShortWrite
}
}
var terminator uint32
if err = binary.Read(reader, binary.BigEndian, &terminator); err != nil {
return "", err
}
if terminator != 0 || written != metadata.Size {
return "", errors.New("invalid encrypted asset content length")
}
var trailing [1]byte
if _, trailingErr := io.ReadFull(reader, trailing[:]); trailingErr != io.EOF {
return "", errors.New("invalid trailing encrypted asset data")
}
return metadata.OriginalName, nil
}
// DecryptAsset 对应解密。
func DecryptAsset(boxID, diskName string, dek, ciphertext []byte) ([]byte, error) {
plaintext, _, err := DecryptAssetWithName(boxID, diskName, dek, ciphertext)
return plaintext, err
}
// notebookCryptoBackupPath 返回加密笔记本的独立 BoxCrypt 备份路径。
// 该文件在主 conf.json 丢失时用作"此笔记本是加密笔记本"的标识和降级恢复源。
// 与全局 NotebookCrypto 备份(<DataDir>/.siyuan/data-crypto-backup.json)配合使用,
// 全局备份存 MasterSalt/KEKVerifier,per-notebook 备份存 WrappedDEK/WrapNonce。
const notebookCryptoBackupFilename = "notebook-crypto-backup.json"
func notebookCryptoBackupPath(boxID string) string {
return filepath.Join(util.DataDir, boxID, ".siyuan", notebookCryptoBackupFilename)
}
// writeNotebookCryptBackup 写入加密笔记本的 BoxCrypt 备份。
// 仅在 Encrypted=true 的笔记本上调用,配合 CreateEncryptedBox / ChangeMasterPassword 写入。
func writeNotebookCryptBackup(boxID string, crypt *conf.BoxEncryption) error {
if !ast.IsNodeIDPattern(boxID) {
return errors.New("invalid notebook ID")
}
if err := filesys.CheckDocumentAddressing(boxID); err != nil {
return err
}
if err := validateBoxEncryption(crypt); err != nil {
return err
}
backupPath := notebookCryptoBackupPath(boxID)
if err := os.MkdirAll(filepath.Dir(backupPath), 0755); err != nil {
return fmt.Errorf("mkdir notebook crypt backup dir failed: %w", err)
}
data, err := gulu.JSON.MarshalIndentJSON(crypt, "", " ")
if err != nil {
return fmt.Errorf("marshal notebook crypt backup failed: %w", err)
}
if err := filelock.WriteFile(backupPath, data); err != nil {
return fmt.Errorf("write notebook crypt backup failed: %w", err)
}
return nil
}
// readNotebookCryptBackup 读取加密笔记本的 BoxCrypt 备份。
// 备份文件不存在时返回 (nil, nil),调用方据此区分"非加密笔记本"和"备份不存在"。
func readNotebookCryptBackup(boxID string) (*conf.BoxEncryption, error) {
if !ast.IsNodeIDPattern(boxID) {
return nil, errors.New("invalid notebook ID")
}
backupPath := notebookCryptoBackupPath(boxID)
if !filelock.IsExist(backupPath) {
return nil, nil
}
return readBoxEncryptionFile(backupPath)
}
func readBoxEncryptionFile(backupPath string) (*conf.BoxEncryption, error) {
data, err := filelock.ReadFile(backupPath)
if err != nil {
return nil, fmt.Errorf("read notebook crypt backup failed: %w", err)
}
var crypt conf.BoxEncryption
if err = gulu.JSON.UnmarshalJSON(data, &crypt); err != nil {
return nil, fmt.Errorf("unmarshal notebook crypt backup failed: %w", err)
}
if err = validateBoxEncryption(&crypt); err != nil {
return nil, err
}
return &crypt, nil
}
// copyAssetDecryptIfEncrypted 把 srcPath 的 asset 复制到 destPath。
// 若 srcPath 在已解锁的加密笔记本下,读密文→解密→写明文到 destPath(导出目录);
// 否则走 filelock.Copy 原路径(字节级复制,密文/明文均可)。
func copyAssetDecryptIfEncrypted(srcPath, destPath string) error {
if err := os.MkdirAll(filepath.Dir(destPath), 0755); err != nil {
return err
}
boxID := util.BoxIDFromDataPath(srcPath)
if boxID != "" && IsEncryptedBox(boxID) {
HoldBoxReadLock(boxID)
defer ReleaseBoxReadLock(boxID)
dek, err := GetDEKIfUnlocked(boxID)
if err != nil {
// 加密笔记本未解锁:fail-closed,拒绝复制(不复制密文,避免泄漏无效文件)
return errors.New(Conf.Language(314))
}
raw, readErr := filelock.ReadFile(srcPath)
if readErr != nil {
return readErr
}
diskName := filepath.Base(srcPath)
plain, decErr := DecryptAsset(boxID, diskName, dek, raw)
if decErr != nil {
return errors.New(Conf.Language(316))
}
if err := filelock.WriteFile(destPath, plain); err != nil {
return err
}
return nil
}
return filelock.Copy(srcPath, destPath)
}
// CreateEncryptedBox 创建一个新的加密笔记本。可多次调用创建多个。
// 前置:加密功能已启用。创建时需要主密码(临时派生 KEK 用于 wrap DEK,用完即弃)。
// 创建后直接用生成的 DEK 打开加密 db 并缓存(已解锁状态),调用方随后调 openNotebook 即可挂载。
func CreateEncryptedBox(name, password string) (id string, err error) {
return createEncryptedBox(name, password, EnsureBoxDoc)
}
func createEncryptedBox(name, password string, initializeBoxDoc func(string) (string, error)) (id string, err error) {
notebookCryptoMu.Lock()
defer notebookCryptoMu.Unlock()
Conf.m.RLock()
notebookCrypto := *Conf.NotebookCrypto
Conf.m.RUnlock()
if !notebookCrypto.Enabled || !notebookCryptoConfigurationComplete(¬ebookCrypto) {
return "", errors.New(Conf.Language(310))
}
kek, err := deriveKEK(password)
if err != nil {
return "", err
}
defer zeroAndClear(kek)
id, err = createBox(name, false)
if err != nil {
return "", err
}
releaseTransition := holdEncryptedBoxTransition(id)
defer releaseTransition()
setEncryptedBoxState(id, EncryptedBoxStateUnlocking)
// 若后续步骤失败,清理已创建的 box 目录和加密 db 文件,避免半创建状态
createdBoxID := id
defer func() {
if err != nil {
setEncryptedBoxState(createdBoxID, EncryptedBoxStateError)
cleanupFailedEncryptedBox(createdBoxID)
id = ""
}
}()
enc, dek, err := WrapNewDEK(id, kek)
if err != nil {
return "", err
}
box := &Box{ID: id}
boxConf := box.GetConf()
boxConf.Encrypted = true
boxConf.BoxCrypt = enc
if err = encryptBoxMetadata(id, boxConf, dek); err != nil {
return "", fmt.Errorf("encrypt notebook metadata failed: %w", err)
}
if err = box.SaveConf(boxConf); err != nil {
return "", fmt.Errorf("save encrypted notebook conf failed: %w", err)
}
if err = writeNotebookCryptBackup(id, enc); err != nil {
return "", fmt.Errorf("write notebook crypt backup failed: %w", err)
}
// 回读校验加密配置已落盘,避免写失败后按普通笔记本处理
verifyConf := box.GetConf()
if verifyConf == nil || !verifyConf.Encrypted || verifyConf.BoxCrypt == nil {
err = errors.New("encrypted notebook metadata verification failed after write")
return "", err
}
markRuntimeEncryptedBox(id)
invalidateEncryptedPublishAccessCache()
// 复用刚派生的 DEK 直接开 db + 缓存,省去再次 Argon2id 解锁
cachedDEKsLock.Lock()
if err = sql.OpenEncryptedDB(id, dek); err != nil {
cachedDEKsLock.Unlock()
return "", err
}
if err = treenode.OpenEncryptedBlockTreeDB(id, dek); err != nil {
sql.CloseEncryptedDB(id)
cachedDEKsLock.Unlock()
return "", err
}
cachedDEKs[id] = dek
cachedDEKsLock.Unlock()
// DEK 和加密数据库就绪后允许内部初始化读取密钥,但在笔记本文档创建完成前不接纳外部请求。
newVal := &atomic.Int64{}
newVal.Store(time.Now().UnixNano())
boxLastAccess.Store(id, newVal)
setEncryptedBoxStateWithAdmission(id, EncryptedBoxStateUnlocked, false)
if _, err = initializeBoxDoc(id); err != nil {
return "", fmt.Errorf("initialize encrypted notebook document failed: %w", err)
}
if err = treenode.SetDocumentMetadataState(id, "ready"); err != nil {
return "", fmt.Errorf("initialize encrypted notebook document metadata failed: %w", err)
}
setEncryptedBoxState(id, EncryptedBoxStateUnlocked)
IncSync()
return id, nil
}
// cleanupFailedEncryptedBox 清理创建失败的加密笔记本,清理目标必须是 DataDir 下的有效笔记本目录。
func cleanupFailedEncryptedBox(boxID string) {
if !ast.IsNodeIDPattern(boxID) {
logging.LogErrorf("refuse to cleanup failed encrypted box with invalid ID [%s]", boxID)
return
}
dataDir := filepath.Clean(util.DataDir)
boxDir := filepath.Clean(filepath.Join(dataDir, boxID))
if boxDir == dataDir || filepath.Dir(boxDir) != dataDir {
logging.LogErrorf("refuse to cleanup failed encrypted box outside data directory [%s]", boxDir)
return
}
// 创建失败路径不经过常规锁定流程,防御性清理可能生成的明文 HEIF 预览缓存。
heif.ClearMemoryCache(boxID)
cachedDEKsLock.Lock()
if cachedDEK, ok := cachedDEKs[boxID]; ok {
zeroAndClear(cachedDEK)
delete(cachedDEKs, boxID)
}
cachedDEKsLock.Unlock()
mountedEncryptedBoxes.Delete(boxID)
boxLastAccess.Delete(boxID)
sql.RemoveEncryptedDBFile(boxID)
treenode.RemoveEncryptedBlockTreeDBFile(boxID)
removeEncryptedBoxLifecycle(boxID)
forgetRuntimeEncryptedBox(boxID)
removeMasterPasswordMigrationBox(boxID)
if err := filelock.Remove(boxDir); err != nil {
logging.LogErrorf("cleanup failed encrypted box [%s]: %s", boxID, err)
}
}
// finalizeSyncedEncryptedBoxRemoval 在同步删除身份文件后等待在途操作结束,再清除本机密钥、挂载和索引生命周期。
func finalizeSyncedEncryptedBoxRemoval(boxID string) {
if !ast.IsNodeIDPattern(boxID) {
return
}
LockBox(boxID)
removeMasterPasswordMigrationBox(boxID)
removeEncryptedBoxLifecycle(boxID)
forgetRuntimeEncryptedBox(boxID)
invalidateEncryptedPublishAccessCache()
}
// zeroAndClear 把密钥字节清零后再置空,尽量减少密钥在内存中的残留时间。
func zeroAndClear(key []byte) {
for i := range key {
key[i] = 0
}
}
// TouchUnlockedEncryptedBoxes 由真实用户交互或 headless 客户端的显式保活调用,刷新当前已解锁笔记本的闲置计时。
func TouchUnlockedEncryptedBoxes() {
now := time.Now().UnixNano()
cachedDEKsLock.RLock()
boxIDs := make([]string, 0, len(cachedDEKs))
for boxID := range cachedDEKs {
boxIDs = append(boxIDs, boxID)
}
cachedDEKsLock.RUnlock()
for _, boxID := range boxIDs {
if val, ok := boxLastAccess.Load(boxID); ok {
val.(*atomic.Int64).Store(now)
}
}
}
// AutoLockIdleEncryptedBoxesJob 检查所有已解锁的加密 notebook,将闲置超时的自动锁定。
// 由 cron 每分钟调用。阈值由 NotebookCrypto.AutoLockMinutes 控制(0 = 禁用)。
func AutoLockIdleEncryptedBoxesJob() {
Conf.m.RLock()
threshold := Conf.NotebookCrypto.AutoLockMinutes
Conf.m.RUnlock()
if threshold <= 0 {
return
}
now := time.Now().UnixNano()
thresholdNs := int64(time.Duration(threshold) * time.Minute)
cachedDEKsLock.RLock()
boxIDs := make([]string, 0, len(cachedDEKs))
for id := range cachedDEKs {
boxIDs = append(boxIDs, id)
}
cachedDEKsLock.RUnlock()
for _, boxID := range boxIDs {
if val, ok := boxLastAccess.Load(boxID); ok {
lastAccess := val.(*atomic.Int64).Load()
elapsed := now - lastAccess
if elapsed >= thresholdNs {
logging.LogInfof("auto-locking idle encrypted notebook [%s] (elapsed=%ds, threshold=%dm)", boxID, elapsed/1e9, threshold)
// 先取笔记本名称再 Unmount:Unmount 会关闭笔记本,之后 Conf.Box 返回 nil 导致提示显示 boxID
boxName := boxID
if box := Conf.Box(boxID); nil != box {
boxName = box.Name
}
Unmount(boxID)
// 自动锁定会关闭正在编辑的文档,推一条提示避免用户以为崩溃
util.PushMsg(fmt.Sprintf(Conf.Language(322), boxName), 0)
}
}
}
}
// SetAutoLockMinutes 设置加密笔记本自动锁定闲置分钟数。0 表示禁用。
func SetAutoLockMinutes(minutes int) {
if minutes < 0 {
minutes = 0
}
Conf.m.Lock()
Conf.NotebookCrypto.AutoLockMinutes = minutes
Conf.m.Unlock()
}