owned this note   changed 3 months ago  
Linked with GitHub

Entropy Keyring Design

The purpose of the keyring is to:

  1. set you up with keys you need to operate with Entropy
  2. support you to persist keys
  3. support you to recover keys from mnemonic
  4. provide helper functions which Entropy SDK consumes for internal functions

Setup paths

Where it comes to instantiating a Keyring there are 3 major pathways we are designing to support

  • Path A - first time user
  • Path B - returning user
  • Path C - recovering

Here's a visualization of all the paths (see them broken down in sub-sections below):

graph LR

A[Path A]--" generateMnemonic() "-->mnemonic
mnemonic--" mnemonicToKeyData()"-->keyData
mnemonic--" *write down* "-->paper[paper?]
keyData--" new Keyring() "-->keyRing
keyRing--" .json()"-->keyData
keyData-. *writeKeyData* .->storage[storage?]

B[Path B]-. *readKeyData* .->keyData

C[Path C]--" *manual entry* "-->mnemonic

classDef entry-point fill:hotpink,stroke:none;
class A,B,C entry-point;

classDef exit-point fill:white,stroke-dasharray:5 5;
class storage,paper exit-point;

Path A - first time user

This user is brand new to Entropy, they want to get set up and running.
Their flow looks like this:

graph LR

A[Path A]--" generateMnemonic() "-->mnemonic
mnemonic--" mnemonicToKeyData()"-->keyData
mnemonic--" *write down* "-->paper[paper?]
keyData--" new Keyring() "-->keyRing
keyRing--" .json()"-->keyData
keyData-. *writeKeyData* .->storage[storage?]


classDef entry-point fill:hotpink,stroke:none;
class A,B,C entry-point;

classDef exit-point fill:white,stroke-dasharray:5 5;
class storage,paper exit-point;

In code:

import { Keyring, generateMnemomnic, mnemonicToKeyData } from `@entropyxyz/keyring`

// 1. create (and write down) mnemonic
const mnemomnic = generateMnemomnic()

// 2. use mnemonic to generate keyData
const keyData = mnemonicToKeyData(mnemonic)
/*
    {
      programMod: { type, secret, public, address },
      developer: { type, secret, public, address },
      device: { type, secret, public, address }
    } 

    where:
    - type = the type of keypair, e.g. blake256
    - secret = the secretKey of the keypair, stored in ...format?
    - public = the publicKey of the keypair, stored in ...format?
    - addresss = the formatted address of the keypair
*/

// 3. instantiate keyring
const keyring = new Keyring(keyData)

// 4. export keyData + persist
const keyData = keyring.json()
/*
    {
      programMod: { type, secret, ... },
      developer: { type, secret, ... },
      device: { type, secret, ... }
    } 
*/
await writeKeyData(keyData) // some function

Notes:

  1. the generation of keyData here is deterministic (mostly)
    • mnemonicToKeyData takes care of mnemonic => seed => keyData (programMod, developer, etc)
    • keyData.device is NOT derived from the seed
      • this key is deliberately design to NOT be recovered from the mnemonic
      • we want all devices to be distiguishable to be able to mitigate for device theft
  2. we do not persist seed
    • this is a security feature, because the seed is used with paths to derive each key in keyData
    • this allows users to e.g. share a dev key without revealing a programMod key

Questions:

  1. is there a password on the mnemonic?
    • mix: could do, but this just feels like putting a password over a password, so meh?
    • frankie: "password" can mean many things, we should talk about "derivation path"
  2. safe persisting of keyData… how, where?
    • i) system keyring is an option
    • ii) encrypted file (seperate from config?)
  3. how do we handle changes in mnemonicToKeyData?
    • e.g. add a new default key, or change the default type for a particular key(s)
    • do we need a "version" D:
    • frankie: no breaking changes expected, we can version the keyring appropriated, and migrations can be handled elsewhere.
  4. do we make mnemonicToKeyData add keyData.device?
    • this makes it non-deterministic
    • but I am scared if people persist the results at this point they will not have their keyData.device
      Image Not Showing Possible Reasons
      • The image file may be corrupted
      • The server hosting the image is unavailable
      • The image path is incorrect
      • The image format is not supported
      Learn More →
    • frankie: agree
  5. keyData formats
    • type
      • a) list the valid types we support initially?
      • b) which types might we need to support in future, and do these have additional data requirements?
    • secret
      • c) what's the encoding? ("0x hex"? base58?)
    • public
      • d) what's the encoding?
    • address
      • e) what's the encoding?
  6. can we rename programMod?
    • Image Not Showing Possible Reasons
      • The image file may be corrupted
      • The server hosting the image is unavailable
      • The image path is incorrect
      • The image format is not supported
      Learn More →
      bikeshed
    • frankie: i'd prefer not to call it it the programMod since it's not that till we register it
    • mix: how about account - we "register" an account, accounts have addresses (derived from this secret?), and account key being the one which can modify the account seems right?
      • frankie: oh yeah… each account can have multiple registrations… I think we need naming which helps us tell clear stories… what is an "account"?

Path B - returning user

This path assume a user already has a working keyData they have read from persistence.

Flow looks like this:

graph LR

keyData--" new Keyring() "-->keyRing
keyRing--" .json()"-->keyData

B[Path B]-. *readKeyData* .->keyData

classDef entry-point fill:hotpink,stroke:none;
class A,B,C entry-point;

classDef exit-point fill:white,stroke-dasharray:5 5;
class storage,paper exit-point;

import { Keyring } from 'entropxyz/keyring'

const keyData = await readKeyData() // some function
// {
//   programMod: { type, secret, ... },
//   developer: { type, secret, ... },
//   device: { type, secret, ... }
// } 

const keyring = new Keyring(keyData)

Notes:

  1. all keys are optional
    • there should be at least one key tho
  2. this keyData is not necessarily the same as the data generated from mnemonic, it could be: user-created, e.g. I make some new data for a new device:
    • completely manually user generated, or spliced together e.g.
    ​​​const newKeyData = mnemonicToKeyData(generateMnemonic())
​​​const keyData = {
​​​  ..., // new keys
​​​  programMod,    // "admin" keys from an earlier install
​​​}
    • Image Not Showing Possible Reasons
      • The image file may be corrupted
      • The server hosting the image is unavailable
      • The image path is incorrect
      • The image format is not supported
      Learn More →
      in this case, this data connot be recovered froma mnemonic alone, as the determinism is broken

Questions:

  1. are all keys required? what are the implications?
    • mix: I really dislike code that's like "check if we have a key", then if we do, use it.
    • frankie: we can just check and throw

Path C - recovering

This path covers the case that a user has lost their setup, but has a record of their mnemonic.
This flow looks like:

graph LR

mnemonic--" mnemonicToKeyData()"-->keyData
keyData--" new Keyring() "-->keyRing
keyRing--" .json()"-->keyData
keyData-. *writeKeyData* .->storage[storage?]

C[Path C]--" *manual entry* "-->mnemonic

classDef entry-point fill:hotpink,stroke:none;
class A,B,C entry-point;

classDef exit-point fill:white,stroke-dasharray:5 5;
class storage,paper exit-point;

In code:

import { Keyring, mnemonicToKeyData } from `@entropyxyz/keyring`

// 1. User recreates keyData
const keyData = mnemonicToKeyData(mnemonic)

// 2. instantiate keyring
const keyring = new Keyring(keyData)

// 3. persistence of keyData
const keyData = keyring.json()
await writeKeyData(keyData) // some function

Notes:

  1. Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
    keyData.device is unique to every device, so:
  • the user MUST persist the new keyData
  1. Image Not Showing Possible Reasons
    • The image file may be corrupted
    • The server hosting the image is unavailable
    • The image path is incorrect
    • The image format is not supported
    Learn More →
    if the original keyData was custom in some way, this recovery path does not work (see Path B, Note 2)

API

new Keyring(keyData: Keydata) => keyRing

keyring.json() => keyData

returns keyData for persistence

TODO: "get key"

Should be able to access:

  • signer needed for creating extrinsics
  • … what else

Should NOT be able to access:

  • is there any internal state we want to explicitly not expose?

e.g.

keyring[keyname].signer
keyring.get(keyname).signer

TODO: "get ephemeral key"

creates a disposable key intended for singal use encryption while signing:

e.g.

keyring.createEphemeralSigner()
keyring.create(type).signer

Helper functions

generateMnemonic() => string

bip39, no password?

mnemonicToKeyData(mnemonic: string, opts) => keyData

  • bip39, no password?
  • needs a clear spec of KeyData
  • might need versioning, migrations?

opts (rename) is added to specify the keys + paths to derive, e.g

{
  programMod: '/path/to/programMod',
  developer: '/path/to/programMod',
  device: Math.random(),
}

isValidKeyData(keyData) => boolean

mix: we should write this early because it makes the number of checks we need to do
everywhere else soooo much lighter if we can tightly check data before ingesting

Other Concerns

Admin / Registration / Sponsorhips

are curent way of thinking is to have an admin key and registration key
the key that pays for registartion and the key that gets set as the programMod

they can be one in the same (infact they are right now)
however they can also be different. In my personal case i would want them to be different

i think also for "sponsorship" reason we should allow them to be different

init
should take all "3" seeds but only requires programMod i'm still stuck on this name

hot swap keyring?

should you be able to set a different keyring to an already initialized entropy?

entropy.setKeyring(keyring)
Select a repo