omy_core/
lib.rs

1//! # omy-core
2//!
3//! omy 加密文件格式的核心实现：格式读写、密钥体系、分块 AEAD、压缩、分片。
4//!
5//! 本 crate **不依赖 FFmpeg**，许可为 `MIT OR Apache-2.0`，可被任意项目复用。
6//! 媒体解码相关能力位于独立的 crate 中，以隔离 GPL 传染。
7//!
8//! ## 权威规范
9//!
10//! 一切实现细节以 `docs/research/02-file-format-spec.md` 为准。本 crate 的
11//! 每个模块都在文档注释中引用对应章节。
12//!
13//! ## 文件结构
14//!
15//! ```text
16//! ┌────────────────────────┐ 0
17//! │ Fixed Header    96 B   │
18//! ├────────────────────────┤ 96
19//! │ Key Slot Area  384 B   │  8 槽 × 48 B
20//! ├────────────────────────┤ 480
21//! │ TLV Area    tlv_len B  │  变长扩展区
22//! ├────────────────────────┤ 480 + tlv_len
23//! │ Header MAC      32 B   │  HMAC-SHA256
24//! ├────────────────────────┤ header_len
25//! │ Encrypted Payload      │  分块 AEAD
26//! └────────────────────────┘
27//! ```
28//!
29//! `header_len = 96 + 384 + tlv_len + 32`
30//!
31//! ## 字节序
32//!
33//! **全部多字节整数为小端序**，唯一例外是载荷 nonce 与 AAD 中的块序号
34//! （大端序，遵循 STREAM 构造惯例）。
35//!
36//! ## 安全要点
37//!
38//! - 两级 KDF：`Argon2id` 派生的 [`Kek`] 必须在会话内缓存，
39//!   每文件用 HKDF 微秒级派生子密钥。详见 [`crypto`] 模块文档。
40//! - 头部 MAC 在解包出 FEK 后**立即**验证，失败必须终止。
41//! - 未使用的 key slot 填充随机字节，这是可否认性的前提。
42
43#![forbid(unsafe_code)]
44#![warn(missing_docs)]
45// 测试代码中 unwrap 与索引是合理的：失败即测试失败，且下标均为已知常量。
46// 只对 cfg(test) 编译单元放宽，库代码仍受严格 lint 约束——
47// 库代码处理不可信输入，任何 panic 路径都是拒绝服务缺陷。
48#![cfg_attr(
49    test,
50    allow(
51        clippy::unwrap_used,
52        clippy::indexing_slicing,
53        clippy::cast_possible_truncation,
54        clippy::arithmetic_side_effects
55    )
56)]
57
58pub mod container;
59pub mod crypto;
60pub mod error;
61pub mod file;
62pub mod fsatomic;
63pub mod header;
64pub mod keyslot;
65pub mod pack;
66pub mod payload;
67pub mod recovery;
68pub mod reencrypt;
69pub mod restore;
70pub mod scan;
71pub mod session;
72pub mod shard;
73pub mod slot;
74pub mod slotdir;
75pub mod source;
76pub mod unpack;
77pub mod dirname;
78pub mod devicekey;
79pub mod dirsidecar;
80pub mod tlv;
81pub mod tree;
82pub mod util;
83pub mod wordlist;
84
85pub use container::{ContainerBuilder, ContainerEntry, ContainerIndex, EntryKind, EntryMeta};
86pub use crypto::{Argon2Params, CipherId, Fek, Kek, SecretKey};
87pub use error::{Error, ExitCode, Result};
88pub use file::{
89    EncryptOptions, EncryptedFile, OpenedFile, RandomMaterial, encrypt, is_omy_file, open,
90    open_with_password, peek_header,
91};
92pub use fsatomic::{AtomicWriter, TempPlaintext, write_atomic};
93pub use header::{FixedHeader, MAGIC_FILE, MAGIC_SHARD, flags};
94pub use recovery::{RecoveryCode, ParseError as RecoveryParseError};
95pub use scan::{ScanHit, ScanOptions, ScanResult, UnlockOutcome, probe_file, scan_dir};
96pub use session::{CredentialKind, SessionKeys};
97pub use shard::{ShardHeader, merge, split};
98pub use source::{BlockSource, ContainerEntryView, LocalFileSource, MemorySource, read_source_range};
99pub use tlv::{TlvEntry, TlvSet};
100
101/// 本 crate 实现的格式版本。
102pub const FORMAT_VERSION: (u16, u16) = (header::VERSION_MAJOR, header::VERSION_MINOR);
103
104/// omy 加密文件的扩展名（不含点）。
105pub const FILE_EXTENSION: &str = "omy";
omy_core/lib.rs

omy_core/
lib.rs
