Expand description
§omy-core
omy 加密文件格式的核心实现：格式读写、密钥体系、分块 AEAD、压缩、分片。
本 crate 不依赖 FFmpeg，许可为 MIT OR Apache-2.0，可被任意项目复用。
媒体解码相关能力位于独立的 crate 中，以隔离 GPL 传染。
§权威规范
一切实现细节以 docs/research/02-file-format-spec.md 为准。本 crate 的
每个模块都在文档注释中引用对应章节。
§文件结构
┌────────────────────────┐ 0
│ Fixed Header 96 B │
├────────────────────────┤ 96
│ Key Slot Area 384 B │ 8 槽 × 48 B
├────────────────────────┤ 480
│ TLV Area tlv_len B │ 变长扩展区
├────────────────────────┤ 480 + tlv_len
│ Header MAC 32 B │ HMAC-SHA256
├────────────────────────┤ header_len
│ Encrypted Payload │ 分块 AEAD
└────────────────────────┘header_len = 96 + 384 + tlv_len + 32
§字节序
全部多字节整数为小端序，唯一例外是载荷 nonce 与 AAD 中的块序号 （大端序，遵循 STREAM 构造惯例）。
§安全要点
Re-exports§
pub use container::ContainerBuilder;pub use container::ContainerEntry;pub use container::ContainerIndex;pub use container::EntryKind;pub use container::EntryMeta;pub use crypto::Argon2Params;pub use crypto::CipherId;pub use crypto::Fek;pub use crypto::Kek;pub use crypto::SecretKey;pub use error::Error;pub use error::ExitCode;pub use error::Result;pub use file::EncryptOptions;pub use file::EncryptedFile;pub use file::OpenedFile;pub use file::RandomMaterial;pub use file::encrypt;pub use file::is_omy_file;pub use file::open;pub use file::open_with_password;pub use file::peek_header;pub use fsatomic::AtomicWriter;pub use fsatomic::TempPlaintext;pub use fsatomic::write_atomic;pub use header::FixedHeader;pub use header::MAGIC_FILE;pub use header::MAGIC_SHARD;pub use header::flags;pub use recovery::RecoveryCode;pub use recovery::ParseError as RecoveryParseError;pub use scan::ScanHit;pub use scan::ScanOptions;pub use scan::ScanResult;pub use scan::UnlockOutcome;pub use scan::probe_file;pub use scan::scan_dir;pub use session::CredentialKind;pub use session::SessionKeys;pub use shard::ShardHeader;pub use shard::merge;pub use shard::split;pub use source::BlockSource;pub use source::ContainerEntryView;pub use source::LocalFileSource;pub use source::MemorySource;pub use source::read_source_range;pub use tlv::TlvEntry;pub use tlv::TlvSet;
Modules§
- container
- 目录容器（模式 A）：把整个文件夹打包进单个
.omy。 - crypto
- 密码学层：两级 KDF、AEAD 抽象、密钥材料的安全擦除。
- devicekey
- 设备密钥：把一把随机 KEK 交给这台机器的 OS 密钥库保管。
- dirname
- 树形模式的目录名加密（文档 05 §3.2、§3.3）。
- dirsidecar
- 目录名的钥匙包裹边车（
.omy-name）。 - error
- 错误类型。
- file
- 顶层封装：完整的加密文件读写。
- fsatomic
- 原子文件写入与临时明文文件的生命周期管理。
- header
- 格式常量与 Fixed Header 编解码。
- keyslot
- slot 区的原地改写：增删改密码，不触碰载荷。
- pack
- 把一个目录打包成容器载荷。
- payload
- 载荷层：分块 AEAD 加解密、随机访问、zstd 压缩。
- recovery
- 恢复码：256 bit 熵 → 26 个词，带能定位到词的校验和。
- reencrypt
- 真正的密钥轮换：换掉 FEK 并重新加密载荷。
- restore
- 把容器里保存的元数据还原到落盘的文件上。
- scan
- 目录扫描：找出 .omy 文件并用已缓存的凭据自动匹配。
- session
- 会话密钥缓存与自动锁定。
- shard
- 分片格式：切分、合并、冗余头恢复（规范 §8）。
- slot
- Key Slot Area 的读写。
- slotdir
- 槽位目录（
TLV_SLOT_DIRECTORY，规范 §3.5）。 - source
BlockSource：密文块的统一来源抽象。- tlv
- TLV 扩展区的编解码。
- tree
- 树形模式：逐文件加密并保持目录结构（文档 05 §3，决策 D-05）。
- unpack
- 把容器载荷展开到磁盘。
- util
- 内部工具：随机数、小端序读写、常量时间比较。
- wordlist
- SLIP-39 英文词表（1024 词），公有领域。
Constants§
- FILE_
EXTENSION - omy 加密文件的扩展名（不含点）。
- FORMAT_
VERSION - 本 crate 实现的格式版本。