LanMountainDesktop/docs/INSTALLER_SECURITY.md

# 安装器安全模型

## 威胁模型

### 1. 清单篡改（Manifest Tampering）

**威胁**：攻击者篡改远程清单文件，注入恶意插件版本或下载地址。

**缓解措施**：
- `ManifestSignatureVerifier` 使用 Ed25519 离线签名验证清单完整性
- 签名约定：清单 URL 附加 `.sig` 后缀即为对应签名文件（分离签名）
- 公钥通过环境变量 `LANMOUNTAIN_PLONDS_MANIFEST_PUBKEY` 或编译时常量配置
- 密钥未配置时（占位符模式），验证自动跳过并记录警告——流水线可正常运行

### 2. 源注入（Source Injection via AddManifestSources）

**威胁**：攻击者通过 `AddManifestSources` 机制注入恶意清单源。

**缓解措施**：
- 清单源列表由应用配置控制，不接受运行时外部输入
- 每个源的清单均经过 `ManifestSignatureVerifier` 验证
- 恶意源的篡改清单无法通过签名验证

### 3. 校验和自循环（Checksum Self-Consistency Loop）

**威胁**：攻击者同时修改文件内容和对应校验和，使自校验失效。

**缓解措施**：
- 清单签名覆盖完整清单内容（包括校验和字段）
- 即使攻击者修改了校验和，签名验证仍会失败
- 签名使用 Ed25519 公钥密码学，无法伪造

### 4. DLL 植入（DLL Planting / DLL Hijacking）

**威胁**：攻击者在 `%LOCALAPPDATA%` 路径放置恶意 DLL，利用 `SetDllDirectory` 和 PATH 操纵加载优先级。

**缓解措施**：
- 已移除 `NativeDependencyBootstrapper`（原始 gzip 提取 + PATH 前置 + SetDllDirectory 机制）
- 原生库现通过 `PublishSingleFile` + `IncludeNativeLibrariesForSelfExtract` 正常打包
- `EnableCompressionInSingleFile` 确保原生库压缩存储在单文件中
- 运行时自动解压到安全的临时目录，无 DLL 搜索路径操纵

### 5. PE 文件完整性（Authenticode Verification）

**威胁**：安装器捆绑或下载的可执行文件被替换或篡改。

**缓解措施**：
- `AuthenticodeVerifier` 使用 WinVerifyTrust API 验证 PE 文件签名
- 提取签名者主体信息用于审计记录
- 默认为**报告模式**（不阻止执行）
- 环境变量 `LANMOUNTAIN_INSTALLER_REQUIRE_SIGNED=1` 启用强制验证模式

## 组件架构

### ManifestSignatureVerifier

```
ManifestSignatureVerifier
├── Verify(byte[] manifestBytes, string signatureBase64) → bool
├── GetSignatureUrl(string manifestUrl) → string
└── IsConfigured → bool
```

**技术选型**：
- **Ed25519**（.NET 10 BCL 内置，`System.Security.Cryptography.Ed25519`）
- 零外部 NuGet 包依赖
- AOT 安全（无反射，无动态代码生成）
- 签名大小：64 字节；公钥大小：32 字节

### AuthenticodeVerifier

```
AuthenticodeVerifier
├── VerifyFile(string path) → AuthenticodeResult
├── EnforcementEnabled → bool
└── AuthenticodeResult { Status, SignerSubject }
```

**技术选型**：
- Win32 `WinVerifyTrust` P/Invoke（`WINTRUST_ACTION_GENERIC_VERIFY_V2`）
- `X509Certificate.CreateFromSignedFile` 提取签名者信息
- AOT 安全的 DllImport 声明

## 密钥配置运行手册

### 1. 密钥对生成

```powershell
# 使用 .NET 10 内置 Ed25519 工具生成密钥对
# 此脚本生成私钥和公钥文件

$ErrorActionPreference = 'Stop'

# 生成 Ed25519 密钥对
$privateKeyBytes = [byte[]]::new(64)  # Ed25519 种子 + 公钥
$publicKeyBytes = [byte[]]::new(32)

# 使用 .NET 的 Ed25519 类生成密钥
Add-Type -AssemblyName System.Security.Cryptography
$key = [System.Security.Cryptography.Ed25519]::GenerateKeyPair()
$privateKeyBytes = $key.PrivateKey
$publicKeyBytes = $key.PublicKey

# 保存密钥对（私钥需妥善保管，不纳入版本控制）
$keysDir = ".\keys"
New-Item -ItemType Directory -Path $keysDir -Force | Out-Null

[System.IO.File]::WriteAllBytes("$keysDir\manifest_signing.key", $privateKeyBytes)
[System.IO.File]::WriteAllBytes("$keysDir\manifest_signing.pub", $publicKeyBytes)

Write-Host "密钥对已生成："
Write-Host "  私钥: $keysDir\manifest_signing.key"
Write-Host "  公钥: $keysDir\manifest_signing.pub"
Write-Host ""
Write-Host "⚠️  请务必将私钥文件从版本控制中排除！"
```

### 2. 公钥部署

将公钥（Base64 编码）设置为编译时常量或 CI 环境变量：

```powershell
# 读取公钥并转换为 Base64
$publicKey = [System.IO.File]::ReadAllBytes("$keysDir\manifest_signing.pub")
$publicKeyBase64 = [System.Convert]::ToBase64String($publicKey)

Write-Host "公钥 Base64: $publicKeyBase64"
```

**部署位置**：
- 开发环境：设置环境变量 `LANMOUNTAIN_PLONDS_MANIFEST_PUBKEY`
- CI/CD：在构建管道中注入环境变量
- 生产环境：编译时嵌入或安全存储在配置中心

### 3. 清单签名（CI/CD 集成）

```powershell
# 清单签名 PowerShell 片段（用于 CI/CD 管道）
param(
    [Parameter(Mandatory = $true)]
    [string] $ManifestPath,

    [Parameter(Mandatory = $true)]
    [string] $PrivateKeyPath
)

$ErrorActionPreference = 'Stop'

# 读取清单内容
$manifestBytes = [System.IO.File]::ReadAllBytes($ManifestPath)

# 读取私钥
$privateKeyBytes = [System.IO.File]::ReadAllBytes($PrivateKeyPath)

# 使用 Ed25519 签名
$signature = [System.Security.Cryptography.Ed25519]::SignData($manifestBytes, $privateKeyBytes)
$signatureBase64 = [System.Convert]::ToBase64String($signature)

# 写入签名文件（manifest.json.sig）
$sigPath = "$ManifestPath.sig"
[System.IO.File]::WriteAllText($sigPath, $signatureBase64)

Write-Host "清单签名完成："
Write-Host "  清单: $ManifestPath"
Write-Host "  签名: $sigPath"
Write-Host "  签名者: CI/CD Pipeline"
```

### 4. CI/CD 管道集成示例

```yaml
# GitHub Actions 示例
- name: Sign manifest
  run: |
    $manifest = Get-Content "releases/manifest.json" -Raw
    $manifestBytes = [System.Text.Encoding]::UTF8.GetBytes($manifest)
    $key = [System.Convert]::FromBase64String("${{ secrets.MANIFEST_SIGNING_KEY }}")
    $sig = [System.Security.Cryptography.Ed25519]::SignData($manifestBytes, $key)
    [System.IO.File]::WriteAllText("releases/manifest.json.sig", [System.Convert]::ToBase64String($sig))
```

## 环境变量参考

| 变量名 | 值 | 说明 |
|--------|-----|------|
| `LANMOUNTAIN_PLONDS_MANIFEST_PUBKEY` | Base64 编码的 Ed25519 公钥 | 清单签名验证公钥 |
| `LANMOUNTAIN_INSTALLER_REQUIRE_SIGNED` | `1` | 启用 Authenticode 强制验证（默认关闭） |

## 测试

运行安装器安全模块测试：

```bash
dotnet test LanMountainDesktop.Tests.csproj --filter "FullyQualifiedName~InstallerSecurity"
```

测试覆盖：
- Ed25519 签名验证（有效/篡改/空输入）
- 签名 URL 计算
- Authenticode 验证（签名文件/未签名文件/不存在文件）
- 强制验证模式读取

## 已移除的安全风险

### NativeDependencyBootstrapper（已删除）

**原始行为**：
1. 从嵌入资源中 gzip 解压 `libHarfBuzzSharp.dll` 和 `libSkiaSharp.dll` 到 `%LOCALAPPDATA%\LanDesktopPLONDS\Installer\native\{arch}\{version}\`
2. 使用 `SetDllDirectory` 将该路径添加到进程 DLL 搜索路径首位
3. 使用 `NativeLibrary.Load` 显式加载 DLL

**安全风险**：
- DLL 植入：攻击者可在 `%LOCALAPPDATA%` 路径放置恶意 DLL
- 路径操纵：`SetDllDirectory` 改变进程级 DLL 搜索顺序
- 版本目录可预测：攻击者可预先创建目标版本目录

**替代方案**：
- `PublishSingleFile` + `IncludeNativeLibrariesForSelfExtract` 自动打包原生库
- `EnableCompressionInSingleFile` 压缩存储
- 运行时解压到安全的临时目录（由 .NET 运行时管理）