Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/vladimiry/fs-json-store-encryption-adapter
Encryption adapter for https://github.com/vladimiry/fs-json-store
https://github.com/vladimiry/fs-json-store-encryption-adapter
adapter aes-256 argon2 buffer encryption key-derivation pbkdf2 preset sodium
Last synced: 2 months ago
JSON representation
Encryption adapter for https://github.com/vladimiry/fs-json-store
- Host: GitHub
- URL: https://github.com/vladimiry/fs-json-store-encryption-adapter
- Owner: vladimiry
- License: mit
- Created: 2017-12-05T16:36:19.000Z (about 7 years ago)
- Default Branch: master
- Last Pushed: 2024-08-26T20:03:16.000Z (5 months ago)
- Last Synced: 2024-11-08T21:53:54.863Z (3 months ago)
- Topics: adapter, aes-256, argon2, buffer, encryption, key-derivation, pbkdf2, preset, sodium
- Language: TypeScript
- Homepage:
- Size: 609 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# fs-json-store-encryption-adapter
is an encryption adapter for the [fs-json-store](https://github.com/vladimiry/fs-json-store) module.
[](https://github.com/vladimiry/fs-json-store-encryption-adapter/actions)
## Features
- Predefined presets.
- Switching between built-in node's `crypto` and `libsodium` (like Argon2 key derivation function) implementations.
- Keeping all the needed options in the produced buffer in along with the encrypted data itself.
- Random `salting` is enabled for every key derivation and encryption execution, which helps against the lookup tables and rainbow tables hash cracking attacks.
## Implementation Notes
- Module executes a native [libsodium](https://github.com/jedisct1/libsodium) code with help of the [sodium-native](https://github.com/sodium-friends/sodium-native) bindings library. It's supposed to work faster than the WebAssembly versions.
- Module can be used as a general purpose `Buffer` encryption library, adapter simply implements the following interface:
```typescript
export interface Adapter {
write(data: Buffer): Promise;
read(data: Buffer): Promise;
}
```
## Supported Presets
### `key derivation`
- **`type`**: `sodium.crypto_pwhash`
- **`preset`**: `mode:interactive|algorithm:default` - default algorithm as for now is `Argon2id`.
- **`preset`**: `mode:moderate|algorithm:default`
- **`preset`**: `mode:sensitive|algorithm:default`
- **`type`**: `pbkdf2`
- **`preset`**: `mode:interactive|digest:sha256`
- **`preset`**: `mode:moderate|digest:sha256`
- **`preset`**: `mode:sensitive|digest:sha256`
### `encryption`
- **`type`**: `sodium.crypto_secretbox_easy`
- **`preset`**: `algorithm:default`
- **`type`**: `crypto`
- **`preset`**: `algorithm:aes-256-cbc`
You should not rely on the `types / presets` respective inner values, but only on the `types / presets` names listed above. Presets values can be changed in the code in any time (for example, increasing key derivation work factor), but that won't break the decryption of the previously encrypted data since adapter stores all the encryption options in the same buffer and so decryption can be reproduced even if values of the presets have been changed in the code with new module release.
## Usage Examples
Using TypeScript and async/await:
```typescript
import {Model, Store} from "fs-json-store";
import {EncryptionAdapter} from "fs-json-store-encryption-adapter";
interface DataModel extends Partial {
someProperty: string;
}
const password = process.env.STORE_PASSWORD;
if (!password) {
throw new Error("Empty password is not allowed");
}
// data file example
(async () => {
const store = new Store({
file: "./data.bin",
adapter: new EncryptionAdapter({
password,
preset: {
keyDerivation: {type: "sodium.crypto_pwhash", preset: "mode:interactive|algorithm:default"},
encryption: {type: "sodium.crypto_secretbox_easy", preset: "algorithm:default"},
},
}),
});
const data = await store.write({someProperty: "super secret data"}); // writes encrypted data into the `./data.bin` file
console.log(data); // prints stored data
console.log(await store.read()); // reads and prints stored data
})();
// standalone example using default options
(async () => {
const adapter = EncryptionAdapter.default({password});
const dataBuffer = Buffer.from("super secret data");
const encryptedDataBuffer = await adapter.write(dataBuffer);
const decryptedDataBuffer = await adapter.read(encryptedDataBuffer);
console.log(decryptedDataBuffer.toString()); // prints `super secret data`
})();
```
Using JavaScript and Promises:
```javascript
const {Store} = require("fs-json-store");
const {EncryptionAdapter} = require("fs-json-store-encryption-adapter");
const password = process.env.STORE_PASSWORD;
if (!password) {
throw new Error("Empty password is not allowed");
}
// data file example
(() => {
const store = new Store({
file: "./data.bin",
adapter: new EncryptionAdapter({
password,
preset: {
keyDerivation: {type: "pbkdf2", preset: "mode:interactive|digest:sha256"},
encryption: {type: "sodium.crypto_secretbox_easy", preset: "algorithm:default"},
},
}),
});
store
.write({someProperty: "super secret data"}) // writes encrypted data into the `./data.bin` file
.then((data) => console.log(data)) // prints stored data
.then(() => store.read()) // reads stored data
.then(console.log); // prints stored data
})();
// standalone example using default options
(() => {
const adapter = EncryptionAdapter.default({password});
adapter
.write(Buffer.from("super secret data"))
.then((encryptedDataBuffer) => adapter.read(encryptedDataBuffer))
.then((decryptedDataBuffer) => console.log(decryptedDataBuffer.toString())); // prints `super secret data`
})();
```