@omegajs/keypair

Keychain structured to produce attestations and deterministic key pairs using Ed25519.

Install Via L1FE's NPM

npm config set registry https://npm.l1fe.tech
npm install @omegajs/keypair

Install Via L1FE's Git Repository

git clone https://lab.l1fe.tech/omega/keypair.git
cd keypair
npm install

Usage

const Keychain = require('@omegajs/keypair');

const keyInstance = new Keychain();

const currentKey = keyInstance.get(); // fetches the current keypair instance
const specificKey = keyInstance.get('example'); // retrieves a modified keypair instance for 'example'

const subKeychain = keyInstance.sub('test'); // creates a sub keychain modified by 'test'
const nestedSubKeychain = subKeychain.sub('demo'); // further nested sub keychain

// for signing purposes

const signature = currentKey.sign(message);
const pubKey = currentKey.publicKey;

API

keychainInstance = new Keychain(publicKeyOrKeyPair)

Make a new Keychain instance.

const keychainInstance = new Keychain(); // auto-generates a new keypair
const keychainInstance = new Keychain(publicKey); // creates a "readonly" keychain
const keychainInstance = new Keychain(keyPair); // creates a keychain using an existing keypair

keychainInstance.home

References the keypair used to create the Keychain.

keychainInstance.base

Refers to the current active keypair or home if none selected.

keychainInstance.tweak

Points to the current tweak used.

keychainInstance.head

Represents the key pair in use, essentially base + tweak.

keychainInstance = Keychain.from(keyChainOrPublicKeyOrKeyPair)

Functions similarly to the constructor, returning the Keychain if already provided. This is helpful for ensuring compatibility with the Keychain version in your application.

const Keychain = require('@omegajs/keypair');

function customModule (keychainInstance) {
  const keychain = Keychain.from(keychainInstance); // ensures compatibility with installed Keychain version
}

keyPair = keychainInstance.get([nameOrKeyPair])

Acquire a new KeyPair from the Keychain, with an optional name or key pair for pre-modification.

const keyPair = keychainInstance.get(); // retrieves a keypair from the current head
const keyPair = keychainInstance.get('example'); // first modifies with "example"
const keyPair = keychainInstance.get(anotherKeyPair); // modifies with this keypair

keyPair.sign(message)

Allows signing of a message using the key pair.

keyPair.dh(otherPublicKey)

Enables Diffie-Hellman negotiation with another keypair.

keyPair.publicKey

Retrieves the public key of this key pair.

subKeychain = keychainInstance.sub(nameOrKeyPair)

Create a modified sub Keychain using a name or key pair.

const subKeychain = keychainInstance.sub('example'); // modifies the current keychain
const subKeychain = keychainInstance.sub({ publicKey: ... }); // creates a new "readonly" sub keychain
const subKeychain = keychainInstance.sub({ publicKey: ..., scalar: ... }); // creates a modifiable sub keychain

Note that the following keypairs are equivalent:

const keyPair = keychainInstance.get('example');
const keyPair = keychainInstance.sub('example').get();

All modifications are one-way, using this method:

modSeed = blake2b([currentMod ? currentMod.publicKey : blank, modInput]);

Ie, you need to know the previous modification to get to it.

subKeychain = keychainInstance.checkout(publicKeyOrKeyPair)

Creates a new Keychain based on a specific keypair or public key. This keeps the "home" reference, allowing navigation back to the original keychain.

const checkoutKeychain = keychainInstance.checkout(somePublicKey);
// to return to home
const homeKeychain = checkoutKeychain.checkout(checkoutKeychain.home);

Bootstrapping helpers

To easily setup deterministic keychains you can use the following methods to store the seed on disk for your keychain. Note that these might change / be removed as we iterate, and you should try and store your seed elsewhere if possible for maximum security, depending on what you are building.

const keychain = Keychain.openSync('./my-keychain'); // synchronous method
const keychain = await Keychain.open('./my-keychain'); // asynchronous method

License

Apache-2.0