# 安全

> 加密数据库（SQLite3MC）、把生物识别作为访问入口，以及对本地数据的防护。

Source: https://crossfly.dev/zh/docs/best-practices/seguranca — CrossFly documentation. Full docs as one file: https://crossfly.dev/llms-full.txt

# 安全

在设备上保护数据的两大实用支柱：**加密数据库**和**把生物识别作为访问入口**。

## 加密数据库（SQLite3MC）
用一把密钥打开 SQLite——默认采用 **ChaCha20-Poly1305** 加密（或 `SQLCIPHER`）：
```java
byte[] chave = derivarChaveDaSenha(senhaUsuario);   // ⚠️ 用 KDF 从密码派生 — 切勿硬编码
try (SqliteDb db = SqliteDb.open("cofre.db", chave)) {
   // … 透明加密的数据 …
   db.rekey(novaChave);                              // 更换密钥（例如用户改密码时）
}
```
- **无密钥时零成本，有密钥时透明加密**——无密钥就是普通 SQLite；有密钥时，一切都在访问时加密/解密，无需改动你的 SQL。
- **绝不要硬编码密钥。** 用 KDF 从用户密码派生；只把必要的材料保存在平台的密钥库中。
- 在**移除加密**（用 `rekey` 解除保护）时要小心——文件会变为明文可读。

## 把生物识别作为访问入口
在进入敏感区域（财务、个人数据）之前，要求生物识别：
```java
if (Biometry.isAvailable()) {
   Biometry.authenticate("Acessar cofre", "Cancelar", false,
      (res, msg) -> Component.onUI(() -> {
         if (res == Biometry.AuthResult.SUCCESS) abrirCofre();
         else loginPorSenha();                 // 始终有 fallback
      }));
} else {
   loginPorSenha();
}
```
- **生物识别数据永不离开设备**——应用只收到 `SUCCESS`/`FAILURE`/等结果。
- 生物识别是**本地**认证：它**补充**而非取代应用层的认证（服务器登录）。

## 其他注意事项
- **剪贴板：** 不要把秘密信息复制到剪贴板（`Device.clipboardCopy`）——它对其他应用是可访问的。
- **文件/`homeFolder`：** `Device.homeFolder` 中的数据默认不加密——对敏感内容请使用加密数据库。
- **日志：** 不要用 `Debug.log` 记录密码/令牌。

## 最佳实践
- 敏感数据 → **加密 SQLite**；密钥从密码派生（KDF），绝不写在代码里。
- 生物识别作为本地入口 + **始终**提供应用层的兜底方案。
- 不要把秘密放进剪贴板、明文文件或日志。

## 常见错误
- 在代码中硬编码密钥（任何人都能从二进制中提取）。
- 把生物识别当作可以取代服务器登录。
- 把令牌/密码保存在 `homeFolder` 中未加密的文件里。

## 另请参阅
- [用 SQLite 持久化](/docs/data-and-services/storage-sqlite) · [生物识别](/docs/data-and-services/device-biometry)