KdbxWeb is a high-performance javascript library for reading/writing KeePass v2 databases (kdbx) in node.js or browser.
- KdbxWeb
kdbxweb offers the following feature sets:
- runs in browser or node.js
- no native addons
- fast encryption with WebCrypto
- total ≈130kB with dependencies
- full support of Kdbx features
- protected values are stored in memory XOR'ed
- conflict-free merge support
- high code coverage
- strict TypeScript
- All modern browsers
- Chrome / Chromium
- Firefox
- Safari
- Opera
- Edge
- NodeJS
Supported formats are Kdbx3 and Kdbx4, current KeePass file format. Old kdb files (for KeePass v1) are out of scope of this library. We currently have no plans to support the older formats.
Kdbx4 has introduced Argon2, a new hashing function. Due to complex calculations, you have to implement it manually and export to kdbxweb, if you want to support such files. Here's how:
kdbxweb.CryptoEngine.setArgon2Impl((password, salt,
memory, iterations, length, parallelism, type, version
) => {
// your implementation makes hash (Uint8Array, 'length' bytes)
return Promise.resolve(hash);
});You can find an implementation example in tests.
It's not compiled into the library because there's no universal way to provide a fast implementation, so it's up to you to choose the best one.
This section gives usage examples on how you can implement kdbxweb into your project.
let credentials = new kdbxweb.Credentials(kdbxweb.ProtectedValue.fromString('demo'),
keyFileArrayBuffer, challengeResponseFunction);
const db1 = await kdbxweb.Kdbx.load(dataAsArrayBuffer, credentials);
const db2 = await kdbxweb.Kdbx.loadXml(dataAsString, credentials);const dataAsArrayBuffer = await db.save();
const xmlAsString = await db.saveXml();You can also pretty-print XML:
const prettyPrintedXml = await db.saveXml(true);db.header
db.metaSee the corresponding type fields inside, they should be obvious.
const db = await kdbxweb.Kdbx.load(data, credentials);
db.credentials.setPassword(kdbxweb.ProtectedValue.fromString('newPass'));
const randomKeyFile = await kdbxweb.Credentials.createRandomKeyFile();
db.credentials.setKeyFile(randomKeyFile);
await db.save();let newDb = kdbxweb.Kdbx.create(credentials, 'My new db');
let group = newDb.createGroup(newDb.getDefaultGroup(), 'subgroup');
let entry = newDb.createEntry(group);db.cleanup({
historyRules: true,
customIcons: true,
binaries: true
});
// upgrade the db to latest version (currently KDBX4)
db.upgrade();
// downgrade to KDBX3
db.setVersion(3);
// set KDF to AES
db.setKdf(kdbxweb.Consts.KdfId.Aes);Entries, groups and meta are consistent against merging in any direction with any state.
Due to format limitations, p2p entry history merging and some non-critical fields in meta can produce phantom records or deletions,
so correct entry history merging is supported only with one central replica. Items order is not guaranteed but the algorithm tries to preserve it.
let db = await kdbxweb.Kdbx.load(data, credentials); // load local db
// work with db
db.save(); // save local db
let editStateBeforeSave = db.getLocalEditState(); // save local editing state (serializable to JSON)
db.close(); // close local db
db = kdbxweb.Kdbx.load(data, credentials); // reopen it again
db.setLocalEditState(editStateBeforeSave); // assign edit state obtained before save
// work with db
let remoteDb = await kdbxweb.Kdbx.load(remoteData, credentials); // load remote db
db.merge(remoteDb); // merge remote into local
delete remoteDb; // don't use remoteDb anymore
let saved = await db.save(); // save local db
editStateBeforeSave = db.getLocalEditState(); // save local editing state again
let pushedOk = pushToUpstream(saved); // push db to upstream
if (pushedOk) {
db.removeLocalEditState(); // clear local editing state
editStateBeforeSave = null; // and discard it
}let defaultGroup = db.getDefaultGroup();
let anotherGroup = db.getGroup(uuid);
let deepGroup = defaultGroup.groups[1].groups[2];let group = db.createGroup(db.getDefaultGroup(), 'New group');
let anotherGroup = db.createGroup(group, 'Subgroup');db.remove(group);db.move(group, toGroup);
db.move(group, toGroup, atIndex);let recycleBin = db.getGroup(db.meta.recycleBinUuid);
if (!recycleBin) {
db.createRecycleBin();
}for (const entry of group.allEntries()) { /* ... */ }
for (const group of group.allGroups()) { /* ... */ }
for (const entryOrGroup of group.allGroupsAndEntries()) { /* ... */ }let entry = db.getDefaultGroup().entries[0];
entry.fields.AccountNumber = '1234 5678';
entry.fields.Pin = kdbxweb.ProtectedValue.fromString('4321');let entry = db.createEntry(group);// push current state to history stack
entry.pushHistory();
// change something
entry.fgColor = '#ff0000';
// update entry modification and access time
entry.times.update();
// remove states from entry history
entry.removeHistory(index, count);Warning
Do not modify history states directly; this will break merge.
db.remove(entry);db.move(entry, toGroup);If you're moving an entry from another file, this is called import:
db.importEntry(entry, toGroup, sourceFile);Used for passwords and custom fields, stored the value in memory XOR'ed
let value = new kdbxweb.ProtectedValue(xoredByted, saltBytes);
let valueFromString = kdbxweb.ProtectedValue.fromString('str');
let valueFromBinary = kdbxweb.ProtectedValue.fromBinary(data);
let textString = value.getText();
let binaryData = value.getBinary();
let includesSubString = value.includes('foo');try {
await kdbxweb.Kdbx.load(data, credentials);
} catch (e) {
if (e instanceof kdbxweb.KdbxError && e.code === kdbxweb.Consts.ErrorCodes.BadSignature) {
/* ... */
}
}kdbxweb.Consts.ErrorCodes // all thrown errors have code property
kdbxweb.Consts.Defaults // default db settings
kdbxweb.Consts.Icons // icons maplet randomArray = kdbxweb.Crypto.random(/* desired length */ 100);kdbxweb.ByteUtils.bytesToString(bytes);
kdbxweb.ByteUtils.stringToBytes(str);
kdbxweb.ByteUtils.bytesToBase64(bytes);
kdbxweb.ByteUtils.base64ToBytes(str);
kdbxweb.ByteUtils.bytesToHex(bytes);
kdbxweb.ByteUtils.hexToBytes(str);Note
This project requires node v18.18.0.
Use npm to build this project:
npm run buildTo run tests:
npm testkdbxweb includes these 3rd party libraries:
The library provides a number of scripts to work with KDBX files:
Dump the binary header:
npm run script:dump-header my-db.kdbxPrint detailed size information about internal objects:
npm run script:kdbx-size-profiler my-db.kdbx passwordDump the internal XML:
npm run script:kdbx-to-xml my-db.kdbx passwordGenerate big files for load testing:
npm run script:make-big-filesThis library is used in KeeWeb
We also provide a template for HexFiend to explore the contents of KDBX files, you can find it here.
MIT
