Flutter密码管理插件kpasslib的使用

Flutter 密码管理插件 kpasslib 的使用

KPassLib 是一个 Dart 库，用于读取、修改和编写 KeePass v2 数据库（KDBX 版本 3 或 4）。它从 KdbxWeb 移植并重构而来。

功能

• 无需原生插件
• 使用 pointycastle、cryptography_plus 和 hashlib 进行加密
• 完全支持 KDBX 特性
• 受保护的值在内存中与盐进行异或运算
• 支持无冲突合并
• 高代码测试覆盖率
• Dart 3 带有健全的空安全

兼容性

支持 KDBX 版本 3 和 4，即当前的 KeePass 文件格式。旧的 KDB 文件（适用于 KeePass v1）不在范围之内。

使用

加载

final credentials = KdbxCredentials(
  password: ProtectedData.fromString('demo'),
  keyData: demoKey,
  challengeResponse: challengeResponse,
);

final db1 = KdbxDatabase.fromBytes(
  data: TestResources.demoKdbx,
  credentials: credentials,
);

final db2 = KdbxDatabase.fromXmlString(
  xmlString: xml,
  credentials: credentials,
);

保存

final data = db.save();
final xmlString = db.exportToXmlString(pretty: true);

你也可以格式化 XML：

final prettyXml = db.exportToXmlString(pretty: true);

更改凭证

final db = KdbxDatabase.fromBytes(
  data: TestResources.demoKdbx,
  credentials: KdbxCredentials(
    password: ProtectedData.fromString('demo'),
  ),
);

db.header.credentials = KdbxCredentials(
  password: ProtectedData.fromString('new password'),
);

final data = db.save();

创建数据库

final db = KdbxDatabase.create(
  credentials: credentials,
  name: 'Example',
);

final subGroup = db.createGroup(
  parent: db.root,
  name: 'Subgroup',
);

final entry = db.createEntry(parent: subGroup);

维护

db.cleanup(
  history: true,
  icons: true,
  binaries: true,
);

// 升级到最新版本（目前是 KDBX 4.1）
db.upgrade();

// 降级到 KDBX 3.1
db.version = (3, 1);

// 设置 KDF 为 AES
db.kdf = KdfId.aes;

合并

// 加载本地数据库
var db = KdbxDatabase.fromBytes(
  data: localData,
  credentials: credentials,
);

// 工作并保存数据库
db.save();

// 保存本地编辑状态
var state = db.localEditState.toXml().toXmlString();

// 重新打开数据库
db = KdbxDatabase.fromBytes(
  data: fileData,
  credentials: credentials,
);

// 分配之前保存的编辑状态
db.localEditState = KdbxEditState.fromXml(
  XmlDocument.parse(state).firstChild,
);

// 工作并加载远程数据库
final remote = KdbxDatabase.fromBytes(
  data: remoteData,
  credentials: credentials,
);

// 将远程数据合并到本地
db.merge(remote);

// 保存本地数据库
final data = db.save();
db.clearLocalEditState();

群组

final root = db.root;
final anotherGroup = db.root.allItems.firstWhereOrNull(
  (item) => item.uuid == id
);
final deepGroup = db.root.groups[1].groups[2];

创建群组

final group = db.createGroup(
  parent: db.root,
  name: 'New group',
);

final anotherGroup = db.createGroup(
  parent: group,
  name: 'Subgroup',
);

删除项目

db.remove(group);

移动项目

db.move(item: group, target: toGroup);
db.move(item: group, target: toGroup, index: atIndex);

回收站

final recycleBin = db.recycleBin;

递归遍历

db.root.allEntries.forEach((e){/* ... */});
db.root.allGroups.forEach((g){/* ... */});
db.root.allItems.forEach((i){/* ... */});

条目

final entry = db.root.entries.first;
entry.fields['AccountNumber'] = KdbxTextField.fromText(
  text: '1234 5678',
);
entry.fields['PIN'] = KdbxTextField.fromText(
  text: '4321',
  protected: true,
);

创建条目

final entry = db.createEntry(parent: group);

修改条目

// 推送当前状态到历史栈
entry.pushHistory();

// 更改某些内容
entry.foreground = '#ff0000';

// 更新条目的修改时间和访问时间
entry.times.touch();

// 从条目历史中删除状态
entry.removeFromHistory(start: 0, end: 5);

重要：不要直接修改历史状态，这将破坏合并。

导入条目

db.importEntry(
  entry: entry,
  target: toGroup,
  other: sourceFile
);

受保护的数据

final value = ProtectedData.fromProtectedBytes(bytes: value, salt: salt);
final valueFromString = ProtectedData.fromString('str');
final valueFromBinary = ProtectedData.fromBytes(data);
final textString = valueFromString.text;
final binaryData = valueFromBinary.bytes;

错误处理

try {
  KdbxDatabase.fromBytes(
    data: data,
    credentials: credentials,
  );
} on FileCorruptedError catch (e) {
  /// 处理错误
}

测试和生成代码覆盖率

运行测试

使用 VS Code 测试标签页或终端命令：

dart test

生成代码覆盖率报告

使用终端命令：

dart test --coverage=coverage
dart run coverage:format_coverage --lcov --in=coverage --out=coverage/lcov.info --report-on=lib
genhtml coverage/lcov.info -o coverage/

示例代码

以下是一个完整的示例代码：

import 'package:kpasslib/kpasslib.dart';

/// 创建一个新的数据库，对其进行修改，保存并重新加载。
void main() async {
  final credentials = KdbxCredentials(
    password: ProtectedData.fromString('demo'),
    keyData: KdbxCredentials.createRandomKeyFile(version: 2),
  );

  var db = KdbxDatabase.create(
    credentials: credentials,
    name: 'Example',
  );

  final subGroup = db.createGroup(
    parent: db.root,
    name: 'Subgroup',
  );

  final entry = db.createEntry(parent: subGroup);

  entry.fields.addAll({
    'Title': KdbxTextField.fromText(text: 'Title'),
    'UserName': KdbxTextField.fromText(text: 'User'),
    'Password': KdbxTextField.fromText(
      text: 'Password',
      protected: true,
    ),
  });

  final binary = ProtectedBinary(
    protectedData: ProtectedData.fromString(
      'bin.txt content',
    ),
  );

  final reference = db.binaries.add(binary);
  entry.binaries['bin.txt'] = reference;

  entry.pushHistory();
  entry.fields.addAll({
    'Title': KdbxTextField.fromText(text: 'New title'),
    'UserName': KdbxTextField.fromText(text: 'New user'),
    'Password': KdbxTextField.fromText(
      text: 'New password',
      protected: true,
    ),
    'Custom': KdbxTextField.fromText(text: 'Custom'),
    'ProtectedCustom': KdbxTextField.fromText(
      text: 'Protected custom',
      protected: true,
    ),
  });
  entry.times.touch();

  final data = await db.save();
  db = await KdbxDatabase.fromBytes(
    data: data,
    credentials: credentials,
  );
}