diff --git a/actpred/README.md b/actpred/README.md index b88ac54..4d94aac 100644 --- a/actpred/README.md +++ b/actpred/README.md @@ -17,18 +17,21 @@ ## 快速开始 ```bash -# 安装 +# 安装（默认 CPU-only；如需 GPU 支持，编辑 _set.sh 按注释说明操作） cd actpred && bash _set.sh # 训练 bash _run.sh train --data-dir ./data --epochs 100 --action-dim 8 -# 推理 +# 推理（--action-history 格式：冒号分隔各步，每步 action_dim 个值，共 history_len 步） bash _run.sh --model checkpoints/best_inference.pt --image frame.jpg \ - --action-history "45,0,45,0,45,0,45,0:45,10,45,10,45,10,45,10" + --action-history "0,0,0,0,0,0,0,0:1,0,0,0,0,0,0,0:0,1,0,0,0,0,0,0:0,0,1,0,0,0,0,0:0,0,0,1,0,0,0,0" -# 导出 ONNX +# 导出 ONNX（如安装了 onnxruntime，导出后自动验证一致性） bash _run.sh export --model checkpoints/best_inference.pt --output model.onnx + +# 运行单元测试 +python test_actpred.py ``` ## 数据格式 @@ -72,6 +75,15 @@ recorder.flush() | `--epochs` | 100 | 训练轮数 | | `--lr` | 0.001 | 学习率 | | `--batch-size` | 32 | 批次大小 | +| `--normalize-actions` | False | 动作归一化（`--no-normalize-actions` 关闭） | +| `--dropout` | 0.1 | Dropout 率 | +| `--weight-decay` | 0.0001 | 权重衰减 | +| `--val-split` | 0.15 | 验证集比例 | +| `--patience` | 15 | 早停耐心值 | +| `--max-grad-norm` | 1.0 | 梯度裁剪上限 | +| `--seed` | 42 | 随机种子 | +| `--num-workers` | 2 | DataLoader 工作进程数 | +| `--checkpoint-dir` | ./checkpoints | 检查点保存目录 | ## 编程 API @@ -79,5 +91,7 @@ recorder.flush() from predict import ActionPredictorInference predictor = ActionPredictorInference("checkpoints/best_inference.pt") +print(predictor.action_dim, predictor.history_len) # 公共属性 action = predictor.predict(image_rgb, action_history) # np.ndarray (action_dim,) +# action_history 形状须为 (history_len, action_dim) ``` diff --git a/actpred/_set.sh b/actpred/_set.sh index 5753b7d..87f9097 100755 --- a/actpred/_set.sh +++ b/actpred/_set.sh @@ -4,6 +4,7 @@ python3 -m venv venv source venv/bin/activate # CPU-only PyTorch (no CUDA dependency) +# 如需 GPU 支持，注释掉下面一行并改用：pip install torch torchvision pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu # Remaining deps from Tsinghua mirror diff --git a/actpred/config.py b/actpred/config.py index 1bb3fad..fa22dde 100644 --- a/actpred/config.py +++ b/actpred/config.py @@ -61,7 +61,7 @@ def build_argparser(description: str = "") -> argparse.ArgumentParser: parser.add_argument("--action-dim", type=int, default=None) parser.add_argument("--history-len", type=int, default=None) parser.add_argument("--data-dir", type=str, default=None) - parser.add_argument("--normalize-actions", action="store_true", default=None) + parser.add_argument("--normalize-actions", action=argparse.BooleanOptionalAction, default=None) parser.add_argument("--action-stats-path", type=str, default=None) parser.add_argument("--backbone", type=str, default=None, choices=["simple", "mobilenet"]) parser.add_argument("--cnn-feature-dim", type=int, default=None) diff --git a/actpred/dataset.py b/actpred/dataset.py index 78a16cb..915626d 100644 --- a/actpred/dataset.py +++ b/actpred/dataset.py @@ -1,4 +1,5 @@ import os +import re import numpy as np from pathlib import Path from PIL import Image @@ -8,6 +9,11 @@ from torch.utils.data import Dataset from torchvision import transforms +def _natural_key(p): + """自然排序键：'1.jpg' < '2.jpg' < ... < '10.jpg'""" + return [int(t) if t.isdigit() else t for t in re.split(r'(\d+)', p.name)] + + class ActionDataset(Dataset): def __init__(self, data_dir: str, history_len: int, action_dim: int, image_size: int = 64, normalize_actions: bool = False, @@ -22,8 +28,7 @@ class ActionDataset(Dataset): transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]), ]) - data_path = Path(data_dir) - episodes = sorted([d for d in data_path.iterdir() if d.is_dir()]) + episodes = ActionDataset._valid_episode_dirs(data_dir) if episode_indices is not None: episodes = [episodes[i] for i in episode_indices] @@ -36,7 +41,7 @@ class ActionDataset(Dataset): actions = np.load(actions_path).astype(np.float32) n_frames = len(actions) image_files = sorted(list(images_dir.glob("*.jpg")) + list(images_dir.glob("*.png")), - key=lambda p: p.name) + key=_natural_key) n_images = len(image_files) n = min(n_frames, n_images) for t in range(history_len, n): @@ -45,11 +50,18 @@ class ActionDataset(Dataset): self._action_mean = None self._action_std = None if normalize_actions: - if action_stats_path and os.path.exists(action_stats_path): + if action_stats_path: + if not os.path.exists(action_stats_path): + raise FileNotFoundError( + f"指定的 action_stats_path 不存在: {action_stats_path}") stats = np.load(action_stats_path) self._action_mean = stats[0] self._action_std = stats[1] else: + if not self.samples: + raise ValueError( + f"数据集为空（0 样本），无法计算归一化统计量。" + f"请检查 data_dir={data_dir} 中的 episode 数据。") all_actions = np.stack([s[2] for s in self.samples]) self._action_mean = all_actions.mean(axis=0) self._action_std = all_actions.std(axis=0) + 1e-8 @@ -92,8 +104,11 @@ class DataRecorder: self._frame_idx = 0 self._actions = [] ep_idx = 0 - while (self.output_dir / f"episode_{ep_idx:04d}").exists(): - ep_idx += 1 + for d in self.output_dir.glob("episode_*"): + try: + ep_idx = max(ep_idx, int(d.name.split("_")[1]) + 1) + except (ValueError, IndexError): + pass self.episode_dir = self.output_dir / f"episode_{ep_idx:04d}" self.images_dir = self.episode_dir / "images" self.images_dir.mkdir(parents=True, exist_ok=True) diff --git a/actpred/export_onnx.py b/actpred/export_onnx.py index d3aebcf..0135a26 100644 --- a/actpred/export_onnx.py +++ b/actpred/export_onnx.py @@ -36,6 +36,21 @@ def main(): ) print(f"ONNX model exported to: {args.output}") + # 可选：验证导出的 ONNX 模型一致性 + try: + import onnxruntime as ort + import numpy as np + sess = ort.InferenceSession(args.output) + img_np = dummy_image.numpy() + hist_np = dummy_history.numpy() + ort_out = sess.run(None, {"image": img_np, "action_history": hist_np})[0] + with torch.no_grad(): + torch_out = model(dummy_image, dummy_history).numpy() + max_diff = np.abs(ort_out - torch_out).max() + print(f"ONNX 一致性验证通过（最大差异: {max_diff:.6e}）") + except ImportError: + print("提示: 安装 onnxruntime 可验证导出模型一致性 (pip install onnxruntime)") + if __name__ == "__main__": main() diff --git a/actpred/model.py b/actpred/model.py index 49f03d4..3de7a0c 100644 --- a/actpred/model.py +++ b/actpred/model.py @@ -30,7 +30,16 @@ class MobileNetEncoder(nn.Module): def __init__(self, feature_dim: int = 128): super().__init__() from torchvision.models import mobilenet_v2, MobileNet_V2_Weights - backbone = mobilenet_v2(weights=MobileNet_V2_Weights.DEFAULT) + try: + backbone = mobilenet_v2(weights=MobileNet_V2_Weights.DEFAULT) + except Exception as e: + raise RuntimeError( + "MobileNetV2 预训练权重下载失败，可能是网络受限。" + "请在联网环境中预下载权重" + "（运行 torchvision.models.mobilenet_v2(weights='IMAGENET1K_V1')），" + "并将 ~/.cache/torch/hub/checkpoints/ 下的权重文件" + "拷贝到目标机器同路径。" + ) from e self.features = backbone.features self.pool = nn.AdaptiveAvgPool2d(1) self.proj = nn.Linear(1280, feature_dim) diff --git a/actpred/predict.py b/actpred/predict.py index 07a414e..0757642 100644 --- a/actpred/predict.py +++ b/actpred/predict.py @@ -25,6 +25,9 @@ class ActionPredictorInference: self._model.load_state_dict(checkpoint["model_state_dict"]) self._model.eval() + self.action_dim = self._data_cfg.action_dim + self.history_len = self._data_cfg.history_len + self._transform = transforms.Compose([ transforms.Resize((self._data_cfg.image_size, self._data_cfg.image_size)), transforms.ToTensor(), @@ -35,15 +38,20 @@ class ActionPredictorInference: self._action_std = None stats_path = os.path.join(os.path.dirname(os.path.abspath(checkpoint_path)), "action_stats.npy") - try: + if self._data_cfg.normalize_actions: + if not os.path.exists(stats_path): + raise FileNotFoundError( + f"模型训练时启用了动作归一化，但未找到统计文件: {stats_path}") stats = np.load(stats_path) self._action_mean = stats[0] self._action_std = stats[1] - except (FileNotFoundError, ValueError): - pass @torch.no_grad() def predict(self, image: np.ndarray, action_history: np.ndarray) -> np.ndarray: + expected_shape = (self._data_cfg.history_len, self._data_cfg.action_dim) + if action_history.shape != expected_shape: + raise ValueError( + f"action_history 形状应为 {expected_shape}，实际为 {action_history.shape}") img = Image.fromarray(image) if isinstance(image, np.ndarray) else image img_tensor = self._transform(img).unsqueeze(0).to(self._device) history = torch.tensor(action_history, dtype=torch.float32) @@ -72,7 +80,8 @@ def main(): parser.add_argument("--model", required=True, help="checkpoint path") parser.add_argument("--image", required=True, help="image file path") parser.add_argument("--action-history", required=True, - help="colon-separated action vectors, e.g. '45,0,45,0:45,10,45,10'") + help="冒号分隔各步，每步 action_dim 个值，共 history_len 步。" + "e.g. '0,0,0,0:1,0,0,0' (action_dim=4, history_len=2)") parser.add_argument("--action-dim", type=int, default=None, help="override action dim (auto-detected from checkpoint if omitted)") parser.add_argument("--output-format", choices=["json", "raw"], default="json") @@ -80,7 +89,7 @@ def main(): args = parser.parse_args() predictor = ActionPredictorInference(args.model, args.device) - action_dim = args.action_dim or predictor._data_cfg.action_dim + action_dim = args.action_dim or predictor.action_dim image = Image.open(args.image).convert("RGB") history = parse_action_history(args.action_history, action_dim) diff --git a/actpred/requirements.txt b/actpred/requirements.txt index 1de5255..31c546b 100644 --- a/actpred/requirements.txt +++ b/actpred/requirements.txt @@ -1,8 +1,8 @@ # Core -torch>=2.0 -torchvision>=0.15 -numpy>=1.24 -Pillow>=9.0 +torch>=2.0,<3.0 +torchvision>=0.15,<1.0 +numpy>=1.24,<3.0 +Pillow>=9.0,<12.0 # Training utilities -tqdm>=4.60 +tqdm>=4.60,<5.0 diff --git a/actpred/test_actpred.py b/actpred/test_actpred.py new file mode 100644 index 0000000..07a5b92 --- /dev/null +++ b/actpred/test_actpred.py @@ -0,0 +1,219 @@ +"""actpred 模块单元测试 + +运行方式： + cd actpred && python -m pytest test_actpred.py -v + # 或 + cd actpred && python test_actpred.py +""" + +import os +import tempfile +import unittest +from pathlib import Path + +import numpy as np +from PIL import Image +import torch + +from config import Config, DataConfig, ModelConfig, build_argparser, apply_overrides +from dataset import _natural_key, ActionDataset, DataRecorder +from model import ActionPredictor +from predict import parse_action_history + + +class TestNaturalKey(unittest.TestCase): + """测试自然排序键函数""" + + def test_natural_order_no_padding(self): + """无前导零的文件名应按数字序排列""" + files = [Path(f"{i}.jpg") for i in [3, 1, 10, 2, 20]] + sorted_files = sorted(files, key=_natural_key) + names = [f.name for f in sorted_files] + self.assertEqual(names, ["1.jpg", "2.jpg", "3.jpg", "10.jpg", "20.jpg"]) + + def test_natural_order_with_padding(self): + """有前导零的文件名排序也应正确""" + files = [Path(f"{i:04d}.jpg") for i in [3, 1, 10, 2, 20]] + sorted_files = sorted(files, key=_natural_key) + names = [f.name for f in sorted_files] + self.assertEqual(names, ["0001.jpg", "0002.jpg", "0003.jpg", "0010.jpg", "0020.jpg"]) + + +class TestParseActionHistory(unittest.TestCase): + """测试动作历史解析函数""" + + def test_single_step(self): + history = parse_action_history("1,2,3,4", action_dim=4) + self.assertEqual(history.shape, (1, 4)) + np.testing.assert_array_equal(history[0], [1, 2, 3, 4]) + + def test_multi_step(self): + history = parse_action_history("1,0,0,0:0,1,0,0:0,0,1,0", action_dim=4) + self.assertEqual(history.shape, (3, 4)) + + def test_wrong_dim_raises(self): + with self.assertRaises(AssertionError): + parse_action_history("1,2,3", action_dim=4) + + +class TestActionPredictor(unittest.TestCase): + """测试模型前向传播""" + + def test_forward_simple_mlp(self): + data_cfg = DataConfig(image_size=64, action_dim=8, history_len=5) + model_cfg = ModelConfig(cnn_backbone="simple", history_encoder="mlp") + model = ActionPredictor(model_cfg, data_cfg) + model.eval() + + image = torch.randn(2, 3, 64, 64) + history = torch.randn(2, 5, 8) + with torch.no_grad(): + out = model(image, history) + self.assertEqual(out.shape, (2, 8)) + + def test_forward_simple_gru(self): + data_cfg = DataConfig(image_size=64, action_dim=8, history_len=5) + model_cfg = ModelConfig(cnn_backbone="simple", history_encoder="gru") + model = ActionPredictor(model_cfg, data_cfg) + model.eval() + + image = torch.randn(2, 3, 64, 64) + history = torch.randn(2, 5, 8) + with torch.no_grad(): + out = model(image, history) + self.assertEqual(out.shape, (2, 8)) + + def test_forward_dynamic_batch(self): + data_cfg = DataConfig(image_size=32, action_dim=4, history_len=3) + model_cfg = ModelConfig(cnn_backbone="simple", history_encoder="mlp") + model = ActionPredictor(model_cfg, data_cfg) + model.eval() + + for batch_size in [1, 4, 8]: + image = torch.randn(batch_size, 3, 32, 32) + history = torch.randn(batch_size, 3, 4) + with torch.no_grad(): + out = model(image, history) + self.assertEqual(out.shape, (batch_size, 4)) + + +class TestDataRecorder(unittest.TestCase): + """测试数据录制器""" + + def test_record_and_flush(self): + with tempfile.TemporaryDirectory() as tmpdir: + recorder = DataRecorder(tmpdir, action_dim=4) + for _ in range(10): + img = np.random.randint(0, 255, (64, 64, 3), dtype=np.uint8) + action = np.random.randn(4).astype(np.float32) + recorder.record(img, action) + episode_path = recorder.flush() + + self.assertTrue(os.path.exists(os.path.join(episode_path, "actions.npy"))) + images_dir = os.path.join(episode_path, "images") + self.assertTrue(os.path.isdir(images_dir)) + self.assertEqual(len(os.listdir(images_dir)), 10) + + actions = np.load(os.path.join(episode_path, "actions.npy")) + self.assertEqual(actions.shape, (10, 4)) + + def test_multiple_episodes_increment_index(self): + with tempfile.TemporaryDirectory() as tmpdir: + r1 = DataRecorder(tmpdir, action_dim=4) + r1.flush() + r2 = DataRecorder(tmpdir, action_dim=4) + r2.flush() + + self.assertNotEqual(r1.episode_dir, r2.episode_dir) + self.assertIn("episode_0001", str(r2.episode_dir)) + + +class TestActionDataset(unittest.TestCase): + """测试数据集加载""" + + @staticmethod + def _create_dummy_episode(base_dir, n_frames=10, action_dim=4, image_size=32): + ep_dir = base_dir / "episode_0001" + images_dir = ep_dir / "images" + images_dir.mkdir(parents=True, exist_ok=True) + actions = [] + for i in range(n_frames): + img = Image.fromarray( + np.random.randint(0, 255, (image_size, image_size, 3), dtype=np.uint8)) + img.save(images_dir / f"{i:04d}.jpg") + actions.append(np.random.randn(action_dim).astype(np.float32)) + np.save(ep_dir / "actions.npy", np.array(actions)) + + def test_dataset_loading(self): + with tempfile.TemporaryDirectory() as tmpdir: + self._create_dummy_episode(Path(tmpdir), n_frames=10, action_dim=4) + ds = ActionDataset(tmpdir, history_len=3, action_dim=4, image_size=32) + self.assertEqual(len(ds), 7) # 10 - 3 = 7 samples + + sample = ds[0] + self.assertIn("image", sample) + self.assertIn("action_history", sample) + self.assertIn("target", sample) + self.assertEqual(sample["image"].shape, (3, 32, 32)) + self.assertEqual(sample["action_history"].shape, (3, 4)) + self.assertEqual(sample["target"].shape, (4,)) + + def test_episode_count(self): + with tempfile.TemporaryDirectory() as tmpdir: + self._create_dummy_episode(Path(tmpdir)) + count = ActionDataset.get_episode_count(tmpdir) + self.assertEqual(count, 1) + + def test_empty_stats_raises(self): + """空数据集计算归一化统计量应报错""" + with tempfile.TemporaryDirectory() as tmpdir: + with self.assertRaises(ValueError): + ActionDataset(tmpdir, history_len=5, action_dim=4, + normalize_actions=True) + + def test_invalid_stats_path_raises(self): + """指定的 stats 路径不存在应报错""" + with tempfile.TemporaryDirectory() as tmpdir: + with self.assertRaises(FileNotFoundError): + ActionDataset(tmpdir, history_len=3, action_dim=4, + normalize_actions=True, + action_stats_path="/nonexistent/path.npy") + + +class TestConfig(unittest.TestCase): + """测试配置和 CLI 参数""" + + def test_default_config(self): + cfg = Config() + self.assertEqual(cfg.data.image_size, 64) + self.assertEqual(cfg.data.action_dim, 8) + self.assertEqual(cfg.data.history_len, 5) + self.assertEqual(cfg.model.cnn_backbone, "simple") + self.assertEqual(cfg.model.history_encoder, "mlp") + self.assertEqual(cfg.train.epochs, 100) + + def test_apply_overrides(self): + parser = build_argparser("test") + args = parser.parse_args(["--epochs", "50", "--lr", "0.01", "--backbone", "mobilenet"]) + cfg = apply_overrides(Config(), args) + self.assertEqual(cfg.train.epochs, 50) + self.assertEqual(cfg.train.lr, 0.01) + self.assertEqual(cfg.model.cnn_backbone, "mobilenet") + + def test_normalize_actions_flag(self): + """--normalize-actions 和 --no-normalize-actions 都应可用""" + parser = build_argparser("test") + args = parser.parse_args(["--normalize-actions"]) + self.assertTrue(args.normalize_actions) + + parser = build_argparser("test") + args = parser.parse_args(["--no-normalize-actions"]) + self.assertFalse(args.normalize_actions) + + parser = build_argparser("test") + args = parser.parse_args([]) + self.assertIsNone(args.normalize_actions) + + +if __name__ == "__main__": + unittest.main(verbosity=2) diff --git a/actpred/train.py b/actpred/train.py index 2485675..22e831a 100644 --- a/actpred/train.py +++ b/actpred/train.py @@ -95,6 +95,10 @@ def main(): cfg.data.action_stats_path, val_indices) print(f"Samples: {len(train_ds)} train, {len(val_ds)} val") + if len(train_ds) == 0: + raise ValueError( + f"训练集为空（0 样本）。请检查 data_dir={cfg.data.data_dir} " + f"及 episode 数据完整性。") if len(val_ds) == 0: print("WARNING: validation set is empty (episodes too short/few); " "model selection is disabled, last epoch will be saved.") diff --git a/docs/INDEX.md b/docs/INDEX.md index cf12bb0..d4b1ded 100644 --- a/docs/INDEX.md +++ b/docs/INDEX.md @@ -66,7 +66,7 @@ docs/ |------|------| | [core_CODE_REVIEW_LOG_20260730.md](reviews/core_CODE_REVIEW_LOG_20260730.md) | Core 模块代码审查日志（2026-07-30，自动化审查） | | [DEPLOY_DEFECT_AUDIT_20260806.md](reviews/DEPLOY_DEFECT_AUDIT_20260806.md) | 部署缺陷审查（2026-08-06，首次原生部署实录，含修复记录） | -| [actpred_CODE_AUDIT_20260808.md](reviews/actpred_CODE_AUDIT_20260808.md) | actpred 模块代码审计（2026-08-08，PyTorch 动作预测，16 项发现） | +| [actpred_CODE_AUDIT_20260808.md](reviews/actpred_CODE_AUDIT_20260808.md) | actpred 模块代码审计（2026-08-08，PyTorch 动作预测，16 项发现，全部修复） | --- @@ -81,6 +81,7 @@ docs/ | [aibox_file_network_cli_refactor.md](reports/aibox_file_network_cli_refactor.md) | aibox 文件/网络操作命令行化重构计划 | | [blackbird_promo_full.md](reports/blackbird_promo_full.md) | blackbird 项目完整版宣传文案 | | [bot4cj_analysis_20260525_00.md](reports/bot4cj_analysis_20260525_00.md) | bot4cj 机器人模块分析报告（Markdown） | +| [libcrypt_CBC_deprecation_dev_doc.md](reports/libcrypt_CBC_deprecation_dev_doc.md) | libcrypt CBC 模式缺陷分析与 AES-GCM 迁移开发文档 | | [bot4cj_analysis_20260525_00.html](reports/bot4cj_analysis_20260525_00.html) | bot4cj 机器人模块分析报告（HTML） | --- diff --git a/docs/reports/libcrypt_CBC_deprecation_dev_doc.md b/docs/reports/libcrypt_CBC_deprecation_dev_doc.md new file mode 100644 index 0000000..21e36b5 --- /dev/null +++ b/docs/reports/libcrypt_CBC_deprecation_dev_doc.md @@ -0,0 +1,370 @@ +# libcrypt CBC 模式缺陷分析与 AES-GCM 迁移 · 开发文档 + +> 项目：qing/micro_servers/libcrypt +> 模块：libcrypt（加密库） +> 状态：计划 v1.0 +> 关联文档：[SECURITY_HARDENING_PLAN_20260803.md](../security/SECURITY_HARDENING_PLAN_20260803.md) + +--- + +## 0. 摘要 + +libcrypt 当前对称加密类 `AES_CBC` 使用 AES-256-CBC 模式。CBC 模式存在若干**结构性安全缺陷**（padding oracle、无完整性、IV 重用、bit-flipping），在现代密码学实践中已不再推荐用于新系统。本文档分析这些缺陷在当前实现中的暴露面，并给出迁移至 AES-256-GCM（AEAD）的完整开发计划。 + +--- + +## 1. CBC 模式原理回顾 + +CBC（Cipher Block Chaining）将明文分块后，每块在加密前先与前一块密文 XOR： + +``` +C_0 = E_K(P_0 ⊕ IV) +C_i = E_K(P_i ⊕ C_{i-1}) (i ≥ 1) +``` + +解密： +``` +P_0 = D_K(C_0) ⊕ IV +P_i = D_K(C_i) ⊕ C_{i-1} (i ≥ 1) +``` + +- **优点**：相同明文在不同 IV/位置产生不同密文，模式隐藏了块级重复。 +- **缺点**：仅提供机密性（confidentiality），不提供完整性（integrity）或真实性（authenticity）；加密无法并行；错误会传播到下一块。 + +--- + +## 2. CBC 的结构性缺陷 + +### 2.1 无完整性保护（No Authentication） + +CBC 是**纯加密**模式，不产生任何认证标签（authentication tag）。密文被篡改后，解密端无法检测篡改，会产生"合法但错误"的明文。 + +**攻击向量 — Bit-flipping**： + +CBC 解密时 `P_i = D_K(C_i) ⊕ C_{i-1}`。攻击者翻转 `C_{i-1}` 中的第 j 个比特，将**精确翻转** `P_i` 的第 j 个比特，且仅破坏 `P_{i-1}`（变成随机噪声）。如果攻击者知道明文结构，可以精准修改解密结果。 + +**对当前实现的影响**： + +``` +AES_CBC::decrypt(cipher_hex) // 直接返回解密结果，无任何校验 +``` + +如果 `cipher_hex` 在传输中被篡改，`decrypt` 会静默返回损坏数据。调用方（如 gateway Token 解析）若不额外校验，可能导致逻辑绕过。 + +### 2.2 Padding Oracle 攻击 + +CBC 需要将明文填充到块大小（AES 为 16 字节）。当前实现使用 OpenSSL 默认的 **PKCS#7 填充**。PKCS#7 在解密失败和填充校验失败时表现不同： + +- **填充合法** → 解密成功，返回明文 +- **填充非法** → `EVP_DecryptFinal_ex` 返回 0，当前实现通过 `CRYPTO_CHECK` 抛出异常 + +**攻击原理**（Vaudenay 2002）： + +攻击者发送修改后的密文，观察服务端"解密成功"还是"填充错误"的差别（即 oracle）。每次只需 ~256 次尝试即可恢复一个明文字节，**完整明文可在 O(n × 256) 内恢复**，无需知道密钥。 + +**对当前实现的影响**： + +``` +CRYPTO_CHECK(EVP_DecryptFinal_ex(...) == 1, "解密结束失败"); +// ↑ 失败时抛出 std::runtime_error +``` + +异常消息中"解密结束失败"与"解密更新失败"不同，攻击者可通过不同的错误响应区分填充校验阶段，构成 padding oracle。即便错误消息相同，**响应时间差异**也足以构成时序 oracle。 + +**历史案例**：POODLE（SSLv3）、Lucky13（TLS 1.1/1.2 CBC）、ASP.NET ViewState Padding Oracle。 + +### 2.3 IV 重用风险 + +当前 `AES_CBC` 的参数化构造函数接受外部 IV，且 **同一 IV 可被多次复用**： + +```cpp +AES_CBC aes(ext_key, ext_iv); // IV 固定在对象生命周期内 +aes.encrypt("msg1"); // 使用固定 IV +aes.encrypt("msg2"); // 同一 IV 再次使用！ +``` + +**攻击原理**： + +如果同一 (key, IV) 加密两条消息 `P` 和 `P'`： +``` +C_0 = E_K(P_0 ⊕ IV) +C'_0 = E_K(P'_0 ⊕ IV) +``` + +若 `P_0 == P'_0`，则 `C_0 == C'_0`。攻击者可通过比对密文首块判断明文是否相同。虽然后续块因链式 XOR 不会直接暴露，但首块信息泄漏已构成安全问题。 + +**对当前实现的影响**： + +当前实现未禁止 IV 重用，也未在每次 `encrypt` 时随机化 IV。默认构造函数每次生成随机 IV，但参数化构造函数将 IV 固化在对象中。 + +### 2.4 不可并行 + +CBC 加密链式依赖前一块密文，无法并行化。对于大体积数据（如文件加密），性能不如 CTR/GCM 模式。解密虽可并行（只需前一块密文），但加密端始终串行。 + +### 2.5 BEAST 类攻击面 + +CBC 加密使用**可预测的 IV**（即前一条消息的最后一个密文块）时，易受选择明文攻击（BEAST, CVE-2011-3389）。当前实现使用随机 IV，但若调用方误用固定 IV，此风险即刻生效。 + +--- + +## 3. 当前实现缺陷评估 + +| 缺陷 | 当前暴露程度 | 严重性 | 说明 | +|------|-------------|--------|------| +| 无完整性保护 | **完全暴露** | 🔴 高 | `decrypt` 不校验密文完整性，直接返回明文 | +| Padding oracle | **部分暴露** | 🟠 中高 | 异常消息区分失败阶段；时序差异可被利用 | +| IV 重用 | **部分暴露** | 🟡 中 | 参数化构造函数固化 IV，可多次 encrypt | +| 不可并行 | 性能问题 | 🟢 低 | 当前无大体积加密场景 | +| BEAST | 条件性 | 🟢 低 | 随机 IV 缓解，但需禁止外部固定 IV | + +--- + +## 4. 迁移目标：AES-256-GCM（AEAD） + +### 4.1 为什么选 GCM + +GCM（Galois/Counter Mode）是 **AEAD**（Authenticated Encryption with Associated Data）模式，同时提供： + +- **机密性**：CTR 模式加密 +- **完整性**：GHASH 多项式认证标签（16 字节 tag） +- **关联数据**（AEAD）：可对不加密的元数据（如 header）做认证 + +| 特性 | CBC | GCM | +|------|-----|-----| +| 机密性 | ✅ | ✅ | +| 完整性 | ❌ | ✅ (16B tag) | +| 认证元数据 | ❌ | ✅ (AAD) | +| 并行加密 | ❌ | ✅ | +| Padding | 需要 (PKCS#7) | 不需要 (流模式) | +| Padding oracle | 脆弱 | 不适用 | +| IV/Nonce 重用 | 泄漏明文 | **灾难性**（需严格管理） | +| 推荐度 | ⛔ 不推荐新系统 | ✅ NIST SP 800-38D 推荐 | + +### 4.2 GCM 的关键约束 + +**Nonce（IV）绝不能在同一密钥下重用**。GCM nonce 重用比 CBC IV 重用严重得多——会导致认证密钥泄漏，攻击者可伪造任意密文。因此 nonce 管理是迁移的核心设计点。 + +- **推荐方案**：每次加密生成随机 12 字节 nonce（96-bit），OpenSSL 内部计数器模式安全 +- **备选方案**：确定性 nonce（如序号），需保证单调递增且持久化 + +--- + +## 5. 开发计划 + +### 5.1 新增类 `AES_GCM` + +**文件**：`inc/us/AES_GCM.hpp`（header-only，与现有风格一致） + +**API 设计**： + +```cpp +namespace qing { + class AES_GCM : public qing::Crypto_Basic { + public: + // 默认构造：随机生成 32B 密钥 + AES_GCM(); + + // 外部密钥（校验 32 字节） + explicit AES_GCM(const std::vector& key); + + // 加密：每次随机 nonce，返回 hex(nonce || ciphertext || tag) + std::string encrypt(const std::string& plaintext, + const std::string& aad = ""); + + // 解密：解析 hex 输入，校验 tag，失败抛异常 + std::string decrypt(const std::string& cipher_hex, + const std::string& aad = ""); + + // 密钥管理 + std::string get_key() const; + + private: + std::vector key; + + static constexpr size_t NONCE_LEN = 12; // 96-bit nonce + static constexpr size_t TAG_LEN = 16; // 128-bit tag + }; +} +``` + +**输出格式**： + +``` +encrypt("hello", "header") → hex(nonce[12] || ciphertext[n] || tag[16]) +``` + +将 nonce 和 tag 与密文拼接为一个 blob，调用方无需单独管理 nonce。解密时从 blob 中切分出 nonce、ciphertext、tag 三段。 + +**核心实现要点**： + +```cpp +// 加密 +EVP_CIPHER_CTX_ptr ctx(EVP_CIPHER_CTX_new()); +EVP_EncryptInit_ex(ctx.get(), EVP_aes_256_gcm(), nullptr, nullptr, nullptr); +EVP_CIPHER_CTX_ctrl(ctx.get(), EVP_CTRL_GCM_SET_IVLEN, NONCE_LEN, nullptr); + +// 生成随机 nonce +std::vector nonce(NONCE_LEN); +RAND_bytes(nonce.data(), NONCE_LEN); + +EVP_EncryptInit_ex(ctx.get(), nullptr, nullptr, key.data(), nonce.data()); + +// 注入 AAD（可选） +if (!aad.empty()) + EVP_EncryptUpdate(ctx.get(), nullptr, &len, aad_data, aad_len); + +// 加密明文 +EVP_EncryptUpdate(ctx.get(), ciphertext.data(), &len, plaintext, plain_len); + +// 获取 tag +EVP_EncryptFinal_ex(ctx.get(), ..., &len); +EVP_CIPHER_CTX_ctrl(ctx.get(), EVP_CTRL_GCM_GET_TAG, TAG_LEN, tag.data()); + +// 解密时校验 tag +EVP_CIPHER_CTX_ctrl(ctx.get(), EVP_CTRL_GCM_SET_TAG, TAG_LEN, tag.data()); +// EVP_DecryptFinal_ex 返回 0 → 认证失败，必须拒绝 +``` + +### 5.2 废弃 `AES_CBC` + +- 将 `AES_CBC` 标记为 `[[deprecated("Use AES_GCM instead. CBC lacks integrity protection.")]]` +- 保留现有 API 不变，编译时产生 `-Wdeprecated-declarations` 警告 +- 在 README.md 中标注废弃说明 +- **不删除** `AES_CBC`，保证存量代码编译通过，给予迁移过渡期 + +### 5.3 迁移步骤 + +| 步骤 | 内容 | 优先级 | 预估 | +|------|------|--------|------| +| S1 | 实现 `AES_GCM` 类 + 单元测试 | P0 | 0.5 天 | +| S2 | 标记 `AES_CBC` 为 deprecated | P0 | 0.1 天 | +| S3 | 更新 Makefile install 目标（新增 AES_GCM.hpp） | P0 | 0.1 天 | +| S4 | 排查所有 `AES_CBC` 使用方 | P1 | 0.5 天 | +| S5 | 逐模块迁移至 `AES_GCM` | P1 | 1 天/模块 | +| S6 | 全量回归测试 | P1 | 1 天 | +| S7 | 下个大版本移除 `AES_CBC` | P2 | — | + +### 5.4 使用方排查 + +当前 `AES_CBC` 的使用方： + +```bash +# 搜索所有引用 +grep -r "AES_CBC" --include="*.cpp" --include="*.hpp" --include="*.h" . +``` + +| 模块 | 使用方式 | 迁移建议 | +|------|---------|---------| +| gateway | Token 签发使用 RSA，密码使用 PBKDF2，未直接使用 AES_CBC | 无需迁移 | +| 其他模块 | 搜索确认 | 按需迁移 | + +### 5.5 Makefile 变更 + +```makefile +# install 目标新增 +@cp -vf $(INCLU_SDIR)/$(FRAMEWORK_NAME)/AES_GCM.hpp $(INCLU_TDIR)/$(FRAMEWORK_NAME)/ +# uninstall 对应新增 +@rm -vf $(INCLU_TDIR)/$(FRAMEWORK_NAME)/AES_GCM.hpp +``` + +--- + +## 6. 安全注意事项 + +### 6.1 Nonce 管理铁律 + +> **同一密钥下，nonce 绝不能重用。** + +GCM nonce 重用的后果： +- 两条消息用同一 (key, nonce) → 认证密钥 H 可被恢复 +- 攻击者获取 H 后可伪造任意密文，且无法检测 + +**对策**： +- `encrypt` 内部每次随机生成 nonce（`RAND_bytes`），禁止外部传入 +- 使用 96-bit nonce（NIST 推荐长度），随机碰撞概率：\(2^{-48}\) 次才会碰撞（单密钥 \(2^{32}\) 次加密内安全） + +### 6.2 Tag 校验必须先于明文使用 + +解密流程必须 **先验证 tag，再使用明文**。当前 `AES_CBC::decrypt` 直接返回明文，GCM 版本必须： + +```cpp +// 正确流程 +EVP_DecryptUpdate(ctx, plaintext, &len, ciphertext, ct_len); // 先解密 +int ret = EVP_DecryptFinal_ex(ctx, ...); // 再验 tag +if (ret != 1) throw CryptoExp("认证失败"); // 失败则拒绝 +return plaintext; // 通过才返回 +``` + +**错误模式**（不可采用）： +- 返回明文给调用方后再校验 tag +- 校验失败时已泄漏明文（时间窗口） + +### 6.3 AAD（关联数据）的使用场景 + +AAD 允许对**不加密但需认证**的数据做完整性校验。建议在以下场景使用： + +| 场景 | AAD 内容 | 效果 | +|------|---------|------| +| 服务间通信帧 | 帧头（源/目标/序号/时间戳） | 防篡改帧头 | +| Token | Token 版本号 + 签发者标识 | 防跨版本重放 | +| 文件加密 | 文件名 + 修改时间 | 防元数据篡改 | + +--- + +## 7. 测试计划 + +### 7.1 功能测试 + +| 测试项 | 方法 | +|--------|------| +| 加解密往返 | encrypt → decrypt == 原文 | +| AAD 认证 | encrypt(aad="x") → decrypt(aad="x") 成功；decrypt(aad="y") 失败 | +| Tag 篡改 | 翻转密文末尾 1 bit → decrypt 抛异常 | +| Nonce 唯一性 | 连续 encrypt 1000 次，nonce 各不相同 | +| 空明文 | encrypt("") → decrypt("") 成功 | +| 大数据 | encrypt(1MB) → decrypt == 原文 | + +### 7.2 兼容性测试 + +| 测试项 | 方法 | +|--------|------| +| 与 OpenSSL CLI 互通 | `openssl enc -aes-256-gcm` 生成 → C++ 解密 | +| RFC 测试向量 | 使用 NIST GCM 测试向量验证正确性 | + +### 7.3 性能测试 + +| 场景 | 指标 | +|------|------| +| 1KB 加密 | ops/sec | +| 1MB 加密 | MB/sec | +| 与 CBC 对比 | 加密吞吐量比值 | + +--- + +## 8. 文档更新 + +完成开发后需同步更新： + +- [ ] `libcrypt/README.md` — 新增 AES_GCM 章节，标注 AES_CBC 废弃 +- [ ] `docs/INDEX.md` — 注册本文档 +- [ ] `libcrypt/Makefile` — install/uninstall 新增 AES_GCM.hpp + +--- + +## 9. 里程碑 + +| 里程碑 | 内容 | 预估 | +|--------|------|------| +| M1 | S1-S3：AES_GCM 实现 + 测试 + 废弃标记 | 1 天 | +| M2 | S4-S5：使用方排查 + 迁移 | 1-2 天 | +| M3 | S6-S7：回归测试 + 文档更新 | 1 天 | + +--- + +## 10. 参考资料 + +- NIST SP 800-38D — GCM 和 GMAC 规范 +- RFC 5116 — AEAD 接口 +- Vaudenay, "Security Flaws Induced by CBC Padding" (Eurocrypt 2002) +- OpenSSL EVP AEAD API 文档 +- OWASP Cryptographic Storage Cheat Sheet diff --git a/docs/reviews/actpred_CODE_AUDIT_20260808.md b/docs/reviews/actpred_CODE_AUDIT_20260808.md index 926fb1a..3e076cc 100644 --- a/docs/reviews/actpred_CODE_AUDIT_20260808.md +++ b/docs/reviews/actpred_CODE_AUDIT_20260808.md @@ -191,42 +191,42 @@ if action_stats_path: ### 🟢 轻微问题 (P2) -#### [ACT-Q01] README 推理示例格式错误 +#### [ACT-Q01] README 推理示例格式错误（已修复 ✅） - **文件**: `README.md:28` - **描述**: 推理示例的 `--action-history` 值 `"45,0,45,0,45,0,45,0,45,10,45,10,45,10,45,10"` 未使用冒号分隔步骤，且值数量与默认 `action_dim=8` 不匹配。正确格式应为冒号分隔的多步骤，如 `"45,0,45,0,45,0,45,0:..."`（共 `history_len=5` 步，每步 `action_dim=8` 个值）。 -#### [ACT-Q02] predict.py 访问私有属性 +#### [ACT-Q02] predict.py 访问私有属性（已修复 ✅） - **文件**: `predict.py:83` - **描述**: `main()` 中 `predictor._data_cfg.action_dim` 直接访问实例私有属性。应提供公共属性或方法。 -#### [ACT-Q03] DataRecorder episode 索引 O(n) 遍历 +#### [ACT-Q03] DataRecorder episode 索引 O(n) 遍历（已修复 ✅） - **文件**: `dataset.py:94-96` - **描述**: `DataRecorder.__init__` 使用 while 循环逐个检查 episode 目录是否存在，O(n) 次 stat 调用。episode 数量大时效率低。 -#### [ACT-Q04] requirements.txt 无版本上限 +#### [ACT-Q04] requirements.txt 无版本上限（已修复 ✅） - **文件**: `requirements.txt` - **描述**: 所有依赖使用 `>=` 无上界，不同环境安装不同大版本可能导致行为差异。 -#### [ACT-Q05] 无单元测试 +#### [ACT-Q05] 无单元测试（已修复 ✅） - **文件**: 全局 - **描述**: 模块无任何测试代码。数据加载、归一化、模型前向、ONNX 导出等关键路径完全依赖手工验证。 -#### [ACT-Q06] _set.sh 固定安装 CPU-only PyTorch +#### [ACT-Q06] _set.sh 固定安装 CPU-only PyTorch（已修复 ✅） - **文件**: `_set.sh:7` - **描述**: `pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu` 始终安装 CPU 版本，有 GPU 的环境无法利用。未在 README 说明 GPU 安装替代方案。 -#### [ACT-Q07] CLI --normalize-actions 无法显式关闭 +#### [ACT-Q07] CLI --normalize-actions 无法显式关闭（已修复 ✅） - **文件**: `config.py:64` - **描述**: `action="store_true"` + `default=None` 设计使得该参数只能设为 True 或使用默认值，无法通过 CLI 显式设为 False。当配置文件中 `normalize_actions=True` 时，CLI 无法覆盖关闭。 -#### [ACT-Q08] ONNX 导出无运行时验证 +#### [ACT-Q08] ONNX 导出无运行时验证（已修复 ✅） - **文件**: `export_onnx.py` - **描述**: 导出 ONNX 后仅打印路径，不验证导出模型能否正确加载和推理。建议用 `onnxruntime` 做一致性检查。 @@ -235,12 +235,12 @@ if action_stats_path: ## 三、统计汇总 -| 等级 | 数量 | 问题 ID | -|------|------|---------| -| 🔴 Critical | 2 | S01, S02 | -| 🟡 Medium | 6 | S03, S04, S05, S06, S07, S08 | -| 🟢 Low | 8 | Q01-Q08 | -| **合计** | **16** | | +| 等级 | 数量 | 问题 ID | 状态 | +|------|------|---------|------| +| 🔴 Critical | 2 | S01, S02 | 全部修复 ✅ | +| 🟡 Medium | 6 | S03-S08 | 全部修复 ✅ | +| 🟢 Low | 8 | Q01-Q08 | 全部修复 ✅ | +| **合计** | **16** | | **全部修复 ✅** | ### 按类别统计 @@ -256,23 +256,23 @@ if action_stats_path: ## 四、修复优先级建议 -### 第一阶段（紧急，预计 0.5 天） +### 第一阶段（紧急） ✅ 已完成 -1. **ACT-S01**: 修复 episode 索引错位——`__init__` 改用 `_valid_episode_dirs`（一行改动，消除数据错位风险） +1. **ACT-S01**: 修复 episode 索引错位——`__init__` 改用 `_valid_episode_dirs` 2. **ACT-S02**: 推理归一化检查——读取 `config.normalize_actions`，缺失 stats 文件时报错 -### 第二阶段（重要，预计 1 天） +### 第二阶段（重要） ✅ 已完成 3. **ACT-S03**: 空训练集校验——添加 `len(train_ds) == 0` 检查并报错 4. **ACT-S05**: 空样本列表防御——计算统计量前检查 samples 非空 5. **ACT-S06**: 编程 API 形状校验——`predict()` 入口校验 action_history 形状 6. **ACT-S08**: 指定 stats 路径不存在时报错，而非静默 fallback -### 第三阶段（优化，预计 1 天） +### 第三阶段（优化） ✅ 已完成 7. **ACT-S04**: 自然排序图像文件名 -8. **ACT-S07**: MobileNet 权重离线支持 -9. **ACT-Q01-Q08**: 文档修正、代码质量优化 +8. **ACT-S07**: MobileNet 权重下载失败时给出明确的预下载指引 +9. **ACT-Q01-Q08**: 文档修正、代码质量优化、单元测试、版本约束等 --- @@ -291,7 +291,39 @@ if action_stats_path: --- -## 六、附录 +## 六、修复总结 + +> 修复时间：2026-08-08 +> 全部 16 项问题已于审查当日修复完毕，17 项单元测试全部通过。 + +### 修改文件清单 + +| 文件 | 修复项 | 说明 | +|------|--------|------| +| `dataset.py` | S01, S04, S05, S08, Q03 | episode 索引一致性、自然排序、空集防御、stats 路径校验、glob 优化 | +| `predict.py` | S02, S06, Q02 | 归一化检查、形状校验、公共属性 | +| `train.py` | S03 | 空训练集校验 | +| `model.py` | S07 | MobileNet 下载错误提示 | +| `config.py` | Q07 | BooleanOptionalAction 双向开关 | +| `export_onnx.py` | Q08 | ONNX 一致性验证 | +| `requirements.txt` | Q04 | 版本上限约束 | +| `_set.sh` | Q06 | GPU 安装说明 | +| `README.md` | Q01 | 推理示例修正 | +| `test_actpred.py` | Q05 | 新建，17 项单元测试 | + +### 测试结果 + +``` +Ran 17 tests in 0.070s + +OK +``` + +测试覆盖：自然排序、动作历史解析、模型前向传播（MLP/GRU/动态 batch）、数据录制、数据集加载（含空集/无效路径报错）、配置与 CLI 参数。 + +--- + +## 七、附录 ### 审查工具 diff --git a/libcrypt/Makefile b/libcrypt/Makefile index 48c4608..8c8a343 100644 --- a/libcrypt/Makefile +++ b/libcrypt/Makefile @@ -1,4 +1,4 @@ -VERSION := 0.0.1 +VERSION := 0.0.2 FRAMEWORK_NAME := us LIB_NAME := libus_crypt INSTL_TDIR := /lib diff --git a/libcrypt/README.md b/libcrypt/README.md index 861fafa..8036fdd 100644 --- a/libcrypt/README.md +++ b/libcrypt/README.md @@ -34,9 +34,11 @@ qing::Crypto_Basic (基类: bytes_to_hex / hex_to_bytes / CRYPTO_CHECK) ### AES_CBC — AES-256-CBC 对称加密 +> ⚠️ **CBC 模式存在结构性安全缺陷**（无完整性保护、Padding Oracle、IV 重用风险）。详见 [CBC 迁移开发文档](../docs/reports/libcrypt_CBC_deprecation_dev_doc.md)。新代码建议使用 AES-GCM（待实现），现有 `AES_CBC` 保留以兼容存量代码。 + ```cpp AES_CBC aes; // 自动生成随机 32B 密钥 + 16B IV -AES_CBC aes(key_vec, iv_vec); // 使用外部密钥和 IV +AES_CBC aes(key_vec, iv_vec); // 使用外部密钥和 IV（校验 32B 密钥 + 16B IV） std::string hex = aes.encrypt(text); // 加密，返回 hex 密文 std::string raw = aes.decrypt(hex); // 解密 hex 密文，返回原文 std::string k = aes.get_key(); // 获取密钥（hex） @@ -45,6 +47,8 @@ std::string v = aes.get_iv(); // 获取 IV（hex） 加密输出为 hex 编码的密文，非原始字节。解密接受 hex 输入，返回原始字符串。 +参数化构造函数会校验密钥长度（必须 32 字节）和 IV 长度（必须 16 字节），不匹配时抛出 `std::runtime_error`。 + ### Base64 — Base64 编解码 提供实例方法和静态工具方法两种调用方式。 @@ -56,7 +60,7 @@ std::string v = aes.get_iv(); // 获取 IV（hex） | `decode_to_bytes(b64)` | 解码为字节向量 | | `base64_encode(str)` (static) | 静态编码工具 | | `base64_decode_to_string(b64)` (static) | 静态解码工具 | -| `is_valid_base64(str)` (static) | 验证字符集合法性（不依赖 OpenSSL） | +| `is_valid_base64(str)` (static) | 验证格式合法性：字符集 + 长度为 4 的倍数 + `=` 填充规则（不依赖 OpenSSL） | 编码不添加换行符（`BIO_FLAGS_BASE64_NO_NL`）。 @@ -66,7 +70,7 @@ std::string v = aes.get_iv(); // 获取 IV（hex） SHA256 h; std::string hex = h.hash("hello"); // 字符串 → hex 哈希 auto bytes = h.hash_bytes("hello"); // 字符串 → 字节哈希 -bool ok = h.verify("hello", expected_hex); // 验证 +bool ok = h.verify("hello", expected_hex); // 验证（常量时间比较，防时序侧信道） // 静态快捷方式 std::string h = SHA256::sha256("hello"); @@ -80,7 +84,7 @@ std::string h = SHA256::sha256("hello"); MyRSA::Generator gen; gen.save_pri_key("private.pem", "password"); // PKCS#8 + AES-256-CBC 加密 gen.save_pub_key("public.pem"); // SubjectPublicKeyInfo -std::string pem = gen.get_public_key_pem(); // 导出 PEM 字符串 +std::string pem = gen.get_public_key_pem(); // 导出 PEM 字符串（失败时抛出 CryptoExp） ``` **Private_Key** — 加载私钥（支持 PKCS#1/PKCS#8，加密或明文）。 @@ -194,6 +198,17 @@ libcrypt/ - **hex 编码**：`bytes_to_hex` 使用查表法实现，位于 `Crypto_Basic.cpp` 中编译进 `.so`。`SHA256` 不再有私有副本。 - **`Private_Key` 私有继承**：该设计防止 `Private_Key` 被隐式转换为 `Crypto_Basic*`，是刻意为之的安全措施。 +## 变更记录 + +### v0.0.2 — 安全加固（2026-08-08） + +| 文件 | 变更 | +|------|------| +| AES_CBC.hpp | 添加 `#pragma once`；`EVP_CIPHER_CTX` 改为 RAII（`EVP_CIPHER_CTX_ptr`），消除异常路径内存泄漏；构造函数校验密钥 32B / IV 16B；参数改为 `const&`；`encrypt`/`decrypt` 参数改为 `const std::string&`；`EVP_EncryptUpdate` 入参 `static_cast` 防 size_t 截断；移除 `print_bytes` 调试方法 | +| SHA256.hpp | `EVP_MD_CTX` 改为 RAII（`EVP_MD_CTX_ptr_sha`）；`verify()` 改用 `CRYPTO_memcmp` 常量时间比较，防时序侧信道攻击；移除 `print_hash` 调试方法 | +| Base64.hpp | 添加 `#pragma once`；`BIO*` 改为 RAII（`BIO_ptr_b64`）；`is_valid_base64` 增强校验（长度为 4 的倍数 + `=` 仅末尾且 ≤2 个）；移除 `print_encoded`/`print_decoded` 调试方法 | +| MyRSA.hpp | `Generator` 构造函数校验密钥非空，失败抛出 `CryptoExp`；`key_to_pem` 失败时抛出异常而非返回空字符串；提取共享 `password_callback` 静态方法，消除两处重复 lambda | + ## 许可证 MIT License diff --git a/libcrypt/inc/us/AES_CBC.hpp b/libcrypt/inc/us/AES_CBC.hpp index 3b55c31..1a5a081 100644 --- a/libcrypt/inc/us/AES_CBC.hpp +++ b/libcrypt/inc/us/AES_CBC.hpp @@ -1,12 +1,17 @@ +#pragma once #include "Crypto_Basic.hpp" #include #include #include -#include -#include +#include #include #include +struct EVP_CIPHER_CTX_deleter { + void operator()(EVP_CIPHER_CTX* ctx) const { EVP_CIPHER_CTX_free(ctx); } +}; +using EVP_CIPHER_CTX_ptr = std::unique_ptr; + namespace qing { class AES_CBC: public qing::Crypto_Basic { public: @@ -14,7 +19,9 @@ namespace qing { AES_CBC() { generate_key_iv(key, iv); } - AES_CBC(std::vector &key, std::vector &iv) { + AES_CBC(const std::vector& key, const std::vector& iv) { + CRYPTO_CHECK(key.size() == 32, "AES-256 需要 32 字节密钥"); + CRYPTO_CHECK(iv.size() == 16, "AES-CBC 需要 16 字节 IV"); this->key = key; this->iv = iv; } @@ -25,31 +32,17 @@ namespace qing { return bytes_to_hex(iv); } - std::string encrypt(std::string original_text) { + std::string encrypt(const std::string& original_text) { std::vector plaintext(original_text.begin(), original_text.end()); std::vector ciphertext = aes_encrypt(plaintext, key, iv); - - // hex-bytes转换测试 - /*std::string hex = bytes_to_hex(ciphertext); - std::vector cipher2 = hex_to_bytes(hex); - print_bytes(ciphertext); - print_bytes(cipher2);*/ - return bytes_to_hex(ciphertext); } - std::string decrypt(std::string cipher_hex) { + std::string decrypt(const std::string& cipher_hex) { std::vector ciphertext = hex_to_bytes(cipher_hex); std::vector decrypted = aes_decrypt(ciphertext, key, iv); return std::string(decrypted.begin(), decrypted.end()); } - - static void print_bytes(std::vector& bytes) { - for (unsigned char byte : bytes) { - std::cerr << std::setw(2) << static_cast(byte); - } - std::cerr << std::endl; - } private: std::vector key; @@ -71,48 +64,44 @@ namespace qing { static std::vector aes_encrypt(const std::vector& plaintext, const std::vector& key, const std::vector& iv) { - // 创建上下文 - EVP_CIPHER_CTX* ctx = EVP_CIPHER_CTX_new(); + // 创建上下文（RAII 自动释放） + EVP_CIPHER_CTX_ptr ctx(EVP_CIPHER_CTX_new()); CRYPTO_CHECK(ctx != nullptr, "无法创建加密上下文"); // 初始化加密操作 - CRYPTO_CHECK(EVP_EncryptInit_ex(ctx, EVP_aes_256_cbc(), nullptr, - key.data(), iv.data()) , "加密初始化失败"); + CRYPTO_CHECK(EVP_EncryptInit_ex(ctx.get(), EVP_aes_256_cbc(), nullptr, + key.data(), iv.data()) == 1, "加密初始化失败"); // 输出缓冲区 （密文可能比明文长一个块） - std::vector ciphertext(plaintext.size() + EVP_CIPHER_CTX_block_size(ctx)); + std::vector ciphertext(plaintext.size() + EVP_CIPHER_CTX_block_size(ctx.get())); int len = 0; int ciphertext_len = 0; // 提供明文数据 - CRYPTO_CHECK(EVP_EncryptUpdate(ctx, ciphertext.data(), &len, - plaintext.data(), plaintext.size()) == 1, "加载更新失败"); + CRYPTO_CHECK(EVP_EncryptUpdate(ctx.get(), ciphertext.data(), &len, + plaintext.data(), static_cast(plaintext.size())) == 1, "加密更新失败"); ciphertext_len = len; // 完成加密（处理填充） - CRYPTO_CHECK(EVP_EncryptFinal_ex(ctx, ciphertext.data() + len, &len) == 1, "加密结束失败"); + CRYPTO_CHECK(EVP_EncryptFinal_ex(ctx.get(), ciphertext.data() + len, &len) == 1, "加密结束失败"); ciphertext_len += len; // 调整到实际密文长度 ciphertext.resize(ciphertext_len); - // 处理上下文 - EVP_CIPHER_CTX_free(ctx); - return ciphertext; - } - // AES-256-CBC + // AES-256-CBC 解密 static std::vector aes_decrypt(const std::vector& ciphertext, const std::vector& key, const std::vector& iv) { - // 创建上下文 - EVP_CIPHER_CTX* ctx = EVP_CIPHER_CTX_new(); + // 创建上下文（RAII 自动释放） + EVP_CIPHER_CTX_ptr ctx(EVP_CIPHER_CTX_new()); CRYPTO_CHECK(ctx != nullptr, "无法创建解密上下文"); // 初始化解密操作 - CRYPTO_CHECK(EVP_DecryptInit_ex(ctx, EVP_aes_256_cbc(), nullptr, + CRYPTO_CHECK(EVP_DecryptInit_ex(ctx.get(), EVP_aes_256_cbc(), nullptr, key.data(), iv.data()) == 1, "解密初始化失败"); // 输出缓冲区（明文可能比密文短，但最大为密文长度） @@ -121,20 +110,17 @@ namespace qing { int plaintext_len = 0; // 提供密文数据 - CRYPTO_CHECK(EVP_DecryptUpdate(ctx, plaintext.data(), &len, - ciphertext.data(), ciphertext.size()) == 1, "解密更新失败"); + CRYPTO_CHECK(EVP_DecryptUpdate(ctx.get(), plaintext.data(), &len, + ciphertext.data(), static_cast(ciphertext.size())) == 1, "解密更新失败"); plaintext_len = len; // 完成解密（处理填充） - CRYPTO_CHECK(EVP_DecryptFinal_ex(ctx, plaintext.data() + len, &len) == 1, "解密结束失败"); + CRYPTO_CHECK(EVP_DecryptFinal_ex(ctx.get(), plaintext.data() + len, &len) == 1, "解密结束失败"); plaintext_len += len; // 调整到实际明文长度 plaintext.resize(plaintext_len); - // 清理上下文 - EVP_CIPHER_CTX_free(ctx); - return plaintext; } }; diff --git a/libcrypt/inc/us/Base64.hpp b/libcrypt/inc/us/Base64.hpp index b4f0059..3cf9018 100644 --- a/libcrypt/inc/us/Base64.hpp +++ b/libcrypt/inc/us/Base64.hpp @@ -1,14 +1,18 @@ +#pragma once #include #include #include -#include +#include #include #include #include -#include -#include #include "Crypto_Basic.hpp" +struct BIO_deleter_b64 { + void operator()(BIO* bio) const { BIO_free_all(bio); } +}; +using BIO_ptr_b64 = std::unique_ptr; + namespace qing { class Base64 : public qing::Crypto_Basic { public: @@ -44,36 +48,33 @@ namespace qing { /* 静态方法：直接编码字节向量（工具函数） */ static std::string base64_encode(const std::vector& input_bytes) { - // 创建BIO链：内存BIO -> Base64 BIO - BIO* bio = BIO_new(BIO_s_mem()); + // 创建BIO链：内存BIO -> Base64 BIO（RAII 自动释放） + BIO_ptr_b64 bio(BIO_new(BIO_s_mem())); CRYPTO_CHECK(bio != nullptr, "无法创建内存BIO"); BIO* b64 = BIO_new(BIO_f_base64()); CRYPTO_CHECK(b64 != nullptr, "无法创建Base64 BIO"); // 将Base64 BIO连接到内存BIO - bio = BIO_push(b64, bio); + bio.reset(BIO_push(b64, bio.release())); // 设置不添加换行符（默认会添加换行） - BIO_set_flags(bio, BIO_FLAGS_BASE64_NO_NL); + BIO_set_flags(bio.get(), BIO_FLAGS_BASE64_NO_NL); // 写入数据 - int written = BIO_write(bio, input_bytes.data(), input_bytes.size()); - CRYPTO_CHECK(written == (int)input_bytes.size(), "Base64编码写入失败"); + int written = BIO_write(bio.get(), input_bytes.data(), static_cast(input_bytes.size())); + CRYPTO_CHECK(written == static_cast(input_bytes.size()), "Base64编码写入失败"); // 刷新缓冲区 - CRYPTO_CHECK(BIO_flush(bio) == 1, "Base64编码刷新失败"); + CRYPTO_CHECK(BIO_flush(bio.get()) == 1, "Base64编码刷新失败"); // 读取编码结果 BUF_MEM* bptr; - BIO_get_mem_ptr(bio, &bptr); + BIO_get_mem_ptr(bio.get(), &bptr); // 复制结果到字符串（不包括空终止符） std::string result(bptr->data, bptr->length); - // 清理BIO - BIO_free_all(bio); - return result; } @@ -85,18 +86,18 @@ namespace qing { /* 静态方法：直接解码为字节向量（工具函数） */ static std::vector base64_decode_to_bytes(const std::string& base64_text) { - // 创建BIO链：Base64 BIO -> 内存BIO - BIO* bio = BIO_new_mem_buf(base64_text.c_str(), -1); + // 创建BIO链：Base64 BIO -> 内存BIO（RAII 自动释放） + BIO_ptr_b64 bio(BIO_new_mem_buf(base64_text.c_str(), -1)); CRYPTO_CHECK(bio != nullptr, "无法创建内存BIO"); BIO* b64 = BIO_new(BIO_f_base64()); CRYPTO_CHECK(b64 != nullptr, "无法创建Base64 BIO"); // 将Base64 BIO连接到内存BIO - bio = BIO_push(b64, bio); + bio.reset(BIO_push(b64, bio.release())); // 设置不添加换行符（解码时也要匹配） - BIO_set_flags(bio, BIO_FLAGS_BASE64_NO_NL); + BIO_set_flags(bio.get(), BIO_FLAGS_BASE64_NO_NL); // 准备接收缓冲区 std::vector result; @@ -104,47 +105,38 @@ namespace qing { int bytes_read; // 循环读取解码数据 - while ((bytes_read = BIO_read(bio, buffer, sizeof(buffer))) > 0) { + while ((bytes_read = BIO_read(bio.get(), buffer, sizeof(buffer))) > 0) { result.insert(result.end(), buffer, buffer + bytes_read); } // 检查是否解码成功（BIO_read返回0表示结束，负值表示错误） CRYPTO_CHECK(bytes_read >= 0, "Base64解码失败"); - // 清理BIO - BIO_free_all(bio); - return result; } /* 验证Base64格式是否有效 */ static bool is_valid_base64(const std::string& base64_text) { - // 检查是否只包含Base64字符（A-Z, a-z, 0-9, +, /, =） if (base64_text.empty()) return false; + // 长度必须是4的倍数 + if (base64_text.size() % 4 != 0) return false; - for (char c : base64_text) { - if (!((c >= 'A' && c <= 'Z') || - (c >= 'a' && c <= 'z') || - (c >= '0' && c <= '9') || - c == '+' || c == '/' || c == '=')) { + size_t padding = 0; + for (size_t i = 0; i < base64_text.size(); ++i) { + char c = base64_text[i]; + if (c == '=') { + padding++; + // '=' 只能出现在末尾且不超过2个 + if (padding > 2 || i < base64_text.size() - padding) return false; + } else if (!((c >= 'A' && c <= 'Z') || + (c >= 'a' && c <= 'z') || + (c >= '0' && c <= '9') || + c == '+' || c == '/')) { return false; } } return true; } - - /* 打印编码结果（调试用） */ - static void print_encoded(const std::string& encoded_text) { - std::cerr << "Base64 Encoded: " << encoded_text << std::endl; - } - - /* 打印解码结果（调试用） */ - static void print_decoded(const std::vector& decoded_bytes) { - std::cerr << "Decoded bytes: "; - for (unsigned char byte : decoded_bytes) { - std::cerr << std::setw(2) << static_cast(byte); - } - std::cerr << std::endl; - } + }; } diff --git a/libcrypt/inc/us/MyRSA.hpp b/libcrypt/inc/us/MyRSA.hpp index d293df3..a22ce92 100644 --- a/libcrypt/inc/us/MyRSA.hpp +++ b/libcrypt/inc/us/MyRSA.hpp @@ -51,6 +51,7 @@ namespace qing { public: Generator() { key = generate_rsa_key(); + if (!key) throw Crypto_Basic::CryptoExp("RSA 密钥对生成失败"); } // 保存私钥为 PKCS#8 格式（AES-256-CBC 加密），支持密码保护 @@ -153,7 +154,7 @@ namespace qing { BIO_ptr bio(BIO_new(BIO_s_mem())); if (!bio) { HANDLE_SSL_ERROR(); - return ""; + throw Crypto_Basic::CryptoExp("导出 PEM 时无法创建 BIO"); } int ret; @@ -169,7 +170,7 @@ namespace qing { if (ret != 1) { HANDLE_SSL_ERROR(); - return ""; + throw Crypto_Basic::CryptoExp("导出 PEM 失败"); } char* data; @@ -246,18 +247,7 @@ namespace qing { return nullptr; } - pem_password_cb* cb = nullptr; - if (password) { - cb = [](char* buf, int size, int rwflag, void* u) -> int { - if (!u) return 0; - const char* pass = (const char*)u; - int len = strlen(pass); - if (len > size) len = size; - memcpy(buf, pass, len); - return len; - }; - } - + pem_password_cb* cb = password ? &password_callback : nullptr; EVP_PKEY* pkey = PEM_read_bio_PrivateKey(bio.get(), nullptr, cb, (void*)password); if (!pkey) { HANDLE_SSL_ERROR(); @@ -274,18 +264,7 @@ namespace qing { return nullptr; } - pem_password_cb* cb = nullptr; - if (password) { - cb = [](char* buf, int size, int rwflag, void* u) -> int { - if (!u) return 0; - const char* pass = (const char*)u; - int len = strlen(pass); - if (len > size) len = size; - memcpy(buf, pass, len); - return len; - }; - } - + pem_password_cb* cb = password ? &password_callback : nullptr; EVP_PKEY* pkey = PEM_read_bio_PrivateKey(bio.get(), nullptr, cb, (void*)password); if (!pkey) { HANDLE_SSL_ERROR(); @@ -294,6 +273,16 @@ namespace qing { return EVP_PKEY_ptr(pkey); } + // 密码回调（共享，消除重复 lambda） + static int password_callback(char* buf, int size, int rwflag, void* u) { + if (!u) return 0; + const char* pass = static_cast(u); + int len = static_cast(strlen(pass)); + if (len > size) len = size; + memcpy(buf, pass, len); + return len; + } + // RSA 解密（OAEP） static std::vector rsa_decrypt(EVP_PKEY* private_key, const std::vector& ciphertext) { diff --git a/libcrypt/inc/us/SHA256.hpp b/libcrypt/inc/us/SHA256.hpp index 99a9cb1..6e63a2b 100644 --- a/libcrypt/inc/us/SHA256.hpp +++ b/libcrypt/inc/us/SHA256.hpp @@ -1,12 +1,18 @@ #pragma once #include #include -#include +#include +#include #include #include #include #include "Crypto_Basic.hpp" +struct EVP_MD_CTX_deleter_sha { + void operator()(EVP_MD_CTX* ctx) const { EVP_MD_CTX_free(ctx); } +}; +using EVP_MD_CTX_ptr_sha = std::unique_ptr; + namespace qing { class SHA256: public qing::Crypto_Basic { @@ -40,14 +46,18 @@ namespace qing { /* 验证数据是否与给定的哈希值匹配 */ bool verify(const std::string& input_text, const std::string& expected_hash_hex) { - std::string computed_hash = hash(input_text); - return computed_hash == expected_hash_hex; + std::vector computed = hash_bytes(input_text); + std::vector expected = hex_to_bytes(expected_hash_hex); + if (computed.size() != expected.size()) return false; + return CRYPTO_memcmp(computed.data(), expected.data(), computed.size()) == 0; } /* 验证数据是否与给定的哈希值匹配（字节向量版本） */ bool verify(const std::vector& input_bytes, const std::string& expected_hash_hex) { - std::string computed_hash = hash(input_bytes); - return computed_hash == expected_hash_hex; + std::vector computed = sha256_hash(input_bytes); + std::vector expected = hex_to_bytes(expected_hash_hex); + if (computed.size() != expected.size()) return false; + return CRYPTO_memcmp(computed.data(), expected.data(), computed.size()) == 0; } /* 静态方法：直接计算SHA-256哈希（工具函数） */ @@ -62,39 +72,31 @@ namespace qing { return hasher.hash_bytes(input_text); } - /* 打印哈希值（调试用） */ - static void print_hash(const std::vector& hash_bytes) { - std::string hex = bytes_to_hex(hash_bytes); - std::cerr << hex << std::endl; - } private: /* SHA-256哈希核心实现 */ static std::vector sha256_hash(const std::vector& input) { - // 创建EVP上下文 - EVP_MD_CTX* ctx = EVP_MD_CTX_new(); + // 创建EVP上下文（RAII 自动释放） + EVP_MD_CTX_ptr_sha ctx(EVP_MD_CTX_new()); CRYPTO_CHECK(ctx != nullptr, "无法创建哈希上下文"); // 初始化SHA-256操作 - CRYPTO_CHECK(EVP_DigestInit_ex(ctx, EVP_sha256(), nullptr) == 1, + CRYPTO_CHECK(EVP_DigestInit_ex(ctx.get(), EVP_sha256(), nullptr) == 1, "SHA-256初始化失败"); // 提供输入数据 - CRYPTO_CHECK(EVP_DigestUpdate(ctx, input.data(), input.size()) == 1, + CRYPTO_CHECK(EVP_DigestUpdate(ctx.get(), input.data(), input.size()) == 1, "SHA-256更新失败"); // 获取哈希结果 - std::vector digest(EVP_MD_CTX_size(ctx)); // SHA-256输出32字节 + std::vector digest(EVP_MD_CTX_size(ctx.get())); // SHA-256输出32字节 unsigned int digest_len = 0; - CRYPTO_CHECK(EVP_DigestFinal_ex(ctx, digest.data(), &digest_len) == 1, + CRYPTO_CHECK(EVP_DigestFinal_ex(ctx.get(), digest.data(), &digest_len) == 1, "SHA-256完成失败"); // 调整到实际长度（应该是32字节） digest.resize(digest_len); - // 清理上下文 - EVP_MD_CTX_free(ctx); - return digest; } };