local-keys 0.3.0

Simple key management for protecting local data

local-keys has been created to help make encrypting data stored locally in the browser easier.

It uses OpenCrypto as wrapper around the SubtleCrypto for the crypto and provides some simple functions for protecting data and producing an key pair for offline-capable identity.

It is still under heavy development, so is no where near complete

local-key Functions

/**
 * Create a symmetric encryption key from a password
 *
 * @param {string} password Password
 * @params {object} [options]
 * @param {number} [options.iterations] Iterations to use when deriving key
 * @param {Uint8Array|Array<number>} [options.salt] Salt to be added to password
 *   If not given, a ramdom salt will be used
 */
export function createEncryptionKeyFromPassword(password: string, options: any): Promise<{
    salt: any;
    encryptionKey: any;
}>;
/** @typedef {object} EncryptedData
 *
 * @prop {'json'|'string'|'raw'} type Type of data that has been encrypted
 * @prop {Uint8Array} iv Initialisation vector of encryption
 * @prop {ArrayBuffer} encrypted Encrypted data
 */
/**
 * Decrypted some encrypted data using the given key
 *
 * @param {string|number|object|array|Uint8Array} data Data to encrypted
 * @param {CryptoKey} key
 *
 * @return {EncryptedData}
 */
export function encrypt(data: string | number | object | any[] | Uint8Array, key: CryptoKey): EncryptedData;
/**
 * Decrypted some encrypted data using the given key
 *
 * @param {EncryptedData} data
 * @param {CryptoKey} key
 *
 * @return {T}
 *
 * @template T {string|number|object|array|Uint8Array}
 */
export function decrypt<T>(data: EncryptedData, key: CryptoKey): T;
/**
 * Create a asymmetric key pair and protect with a password
 *
 * @param {string} password Password
 * @param {number} [iterations] Iterations to use when deriving key for private
 *   key encryption
 */
export function createProtectedKeyPair(password: string, iterations?: number): Promise<{
    pem: string;
    publicKey: any;
    privateKey: CryptoKey;
}>;
/**
 * Import a asymmetric key pair PEM generated using createProtectedKeyPair
 *
 * @param {string} pem Key pair PEM to import
 * @param {string} password Password used to protect key pair
 */
export function importProtectedKeyPair(pem: string, password: string): Promise<{
    pem: string;
    publicKey: CryptoKey;
    privateKey: any;
}>;
/**
 * Calculate the number of PBKDF2 iterations that will be able to be run
 * in the given time
 *
 * @param {number} time Time in milliseconds
 */
export function guessIterationsForTime(time: number): Promise<number>;
export type EncryptedData = {
    /**
     * Type of data that has been encrypted
     */
    type: "json" | "string" | "raw";
    /**
     * Initialisation vector of encryption
     */
    iv: Uint8Array;
    /**
     * Encrypted data
     */
    encrypted: ArrayBuffer;
};

Vision

The vision for the library is to be used to implement encrypted offline data and authentication for [10-97.org][]. When a user logs in a key pair will be created a stored in the browser. The public key will be given to the server and used for authentication.

Data downloaded, will be encrypted using a symmetric key, which is itself encrypted for each user using a key pair capable of encryption/decryption. This will allow multiple users to be able to access the same stored data.

Data will be signed, but it will be used in an app where there is trust between the users (all users work for the same organisation).

Development

Feel free to post errors or feature requests to the project issue tracker or email them to us. Please submit security concerns as a confidential issue

The source is hosted on Gitlab and uses eslint, prettier, lint-staged and husky to keep things pretty. As such, when you first clone the repository, as well as installing the npm dependencies, you will also need to install husky.

# Install NPM dependencies
npm install
# Set up husky Git hooks stored in .husky
npx husky install

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

0.3.0 - 2024-12-17

Changed

• salt/iterations parameter of createEncryptionFromPassword now passed in options object

Fixed

• Packaging to include index.js

0.2.0 - 2024-12-16

Added

• encrypt() and decrypt() function

Changed

• Return Uint8Array instead of array

0.1.0 - 2024-12-16

Initial version with basic functions!