# ADR - Key/Identity Management

Integration of DPKI during **INSTALLATION** of Holochain so that all apps and app management can operate on top of that security.

## User experience (Human Commons usage):
**Summary:** A wizard walks user through the process of establishing initial security pattern strong enough for the near term future. They can upgrade security as they use Holochain and apps more, such that they are socially connected enough to implement "m of n" trusted user approaches.

### Assumptions
* We can't force people to start up M-of-N because they won't have or know how to find N friends to authorize.
* So we'll start them with a strong revocation key and gamify their future upgrades to more resilient approaches (Level 1 security, Level 2 security, etc. or perhaps semantic tagging on security and then associate levels with sets of semantics)

**Question:** Is multi-factor security just making up for the fact that each of the factors is insecure and vulnerable to central control? Thus a multi-factor attempts to diversify coordination across vulnerability to different centralizers (but mobile phone still ends up being a core vulnerability).

### Scenarios:
1. Initialization (source of seeds)
* Move mouse to generate randomness for master source of seeds (24 - 48 words for generating revocation seed and device seeds), write them down and put them in a safe place. Do not put them in a digital form (unless we make a service that can interface hardware wallets for storing them?)
2. Generation (initial identity for device)
* Click on button to get Nth seed for generating an Identity for a device (uses a deterministic combination of a subset of the 48)
* GenSeed stored locally (encrypted & password protected) used to create the Identity/Address key for each app, and registered with DPKI so you know which Nth number in the seed sequence to use as you keep adding apps.
3. Regeneration (phone dropped in toilet)
4. Revocation (device stolen / compromise of control)

## Tech details:

- 48 (or 24?) words becomes the seed for revocation keys
- Use deterministic combination of a subset (32? words) for seeds for generator keys (one per device)
- Generate next dozen GenSeeds and store the HASH of each in first DPKI chain, so that we can magically bind devices together as controlled by this agent for syncing local data
- Note this means that Generated seeds are actually stored on the device, but the revocation keys aren't!

## Holochain Key/Agent API functions necessary to implement (rust crate; subconsious):

### Order of Seed and Key Generation:
- gen_seed_words(entropy,num_words) -> source_of_seesds_word_list

- gen_revocation_key(source_of_seeds_word_list) -> revocation_pub_key **(NEW)**
// Can we split into 2? gen_revocation_seed(seed_word_list, password) -> revocation_seed && gen_revocation_private_key(revocation_seed)
- get_revocation_private_key(revocation_pub_key) -> revocation_priv_key **(NEW)**
- gen_gen_seed(source_of_seeds_word_list,nth_gen) -> seed
// ? Can we use a clearer name? Is this used to generate 12 mnumonic words from 48 words? Then we need functions generate_generation_mnemonic_words(revocation_mnemonic_words, password, n) -> [generation_mnemonic_words(12)](list size = n)
- gen_key(seed,nth_key) -> private_key
- get_public_key(private_key) -> public_key
- encrypt_key(private_key,password) -> encrypted_key
- decrypt_key(encrypted_key,password) -> private_key
- de/serialize_key(serialized_/encrypted_key) -> serialized_/encrypted_key

- **hardware_wallet integration functions here**

## DPKI Notes:

* DPKI needs to register and publish the public side of this data, but private keys should never transmit over any wire, not even API bridges between local apps. This means the underlying Holochain system must write/encrypt/password protect the priv key files to persistor layer.

* If we register Bridge APIs to the DPKI chain it creates a usability advantage, but it also creates a "centralized" vulnerability where if that DPKI instance/device is compromised, it immediately exposes every app relying on it for key generation and revocation. If there was another way to bridge which did not create this immutable record, and just received inbound calls authorized by keys it knows it has generated, then there's no outward pointer to expose control of all apps.

-----
-----
# Proposals for changes to Core for DPKI
## List of Core Dev Executables:
- Load Revocation Keys into the header
- Generate Revocation Seed and **Keys (new)**
- Generate GenSeeds and Keys
- Private Keys Encryption Decision (Encrypt/Decrypt, Sterilization)

## List of DPKI Intern Executables (DPKI Implementation):

**Login**
- Determine whether it's the user's first time to use Holochain. Call is_init_login()
- First Time: User registers. Create object holo_init_registration
- Returns : Master_Seed, And N Gen_Seeds
- Already registered, but installing Holochain on new device:
- Have Gen_Seed:
- Use the Gen Seed created to link magically to the same account.
- No more Gen_Seed left:
- Use the Master_Seed to create more Gen_Seed

- Old Device Stolen: go to Stolen Recovery
- Old Device Lost: go to Destroy Recovery

**Registration**
- Generate Entropy: gen_entropy(x, y)
- Call gen_seed_words(entropy,num_words) --> seed_word_list (? gne)
- Fields inside revocation keys: dna_hash, revocation_pub_key, user_app_pub_key
- Call gen_rev_key()
- Call gen_gen_seed(seed_word_list,nth_gen) --> Store the Seed_Hash As the anchors for alternate platforms (Laptop, Mobile, etc..)
- Go to New Device.

**New Device**
- Call gen_key(seed,nth_key) returns priv Key
- Choose the Revocation Method
- Default use Level1
- Switch(){level1, level2}
- Level1 security:
- Require 12 mnemonic words
- Level2 security:
- No longer require 12 mnemonic words for the device lost, rather the is generated for the keys
- Require N friends information to reach and recover.
- Store hash(private_Key) Locally (Local Chain?)
- get_public_key(private_key)--> link to the generation_seed_hash (Manager the pub keys linked to the DHT)
- Maintain a Map<generation_seeds, device(mac)>

**Stolen Recovery** (Revocation Process)

- **(Validation For Revocation)**
- **Level 1**
- Use the Master_Seed(i.e. one for each user the 24 or 48 word string).
- Mark the old generation Seed as no longer valid.

- **Level 2**
- Notify you N list friends let them link a signed revocation_key(any string) to your public_key for that App in the DPKI
- Once this is validated the person's identity is verified and create new generation seed.

- **(Revocation Process)**
- **Both Levels**
- If register with a new device, give new generation Seed for that device.
- Create new GenKeys for each app in the previous gen_seed and link them to the new GenSeed Hash

**Destroy Recovery** (Recovery Process)
- Use your seed(i.e. created for each DPKI) or your Master_Seed(i.e. one for each user the 24 or 48 word string)
- Recover exactly the same things on new device.

-----
### Questions ?

- Is there a way to recover your Master_Seed (the GenSeed) if it is lost?

## Graph

digraph tree {
 rankdir=LR;
 size="20,37!" ratio=fill;
 node [shape=record]
  
  {node[color=red; fontcolor=red; fontsize=100]
    MasterSeed }
   
   {node[color=red; fontcolor=red;fontsize=100]
    RevSeed }
   
  {node[color=blue; fontcolor=blue;fontsize=100]
    GenSeed0; GenSeed1; GenSeedN; }
  
  
  {node[color=black; fontcolor=black; fontsize=100]
    Gen0Key0; Gen0Key1; Gen0KeyN;  Gen1Key0; Gen1Key1; Gen1KeyN; GenNKey0; GenNKey1; GenNKeyN;}
  
  
  MasterSeed [label="MasterSeed\n(24 words)"]
  Gen0Key0 [label="{Gen0Key0 |{AuthorKeyPair|NetworkKeyPair}}"]
  Gen0Key1 [label="{Gen0Key1 |{AuthorKeyPair|NetworkKeyPair}}"]
  Gen0KeyN [label="{Gen0KeyN |{AuthorKeyPair|NetworkKeyPair}}"]
  
  Gen1Key0 [label="{Gen1Key0 |{AuthorKeyPair|NetworkKeyPair}}"]
  Gen1Key1 [label="{Gen1Key1 |{AuthorKeyPair|NetworkKeyPair}}"]
  Gen1KeyN [label="{Gen1KeyN |{AuthorKeyPair|NetworkKeyPair}}"]
  
  GenNKey0 [label="{GenNKey0 |{AuthorKeyPair|NetworkKeyPair}}"]
  GenNKey1 [label="{GenNKey1 |{AuthorKeyPair|NetworkKeyPair}}"]
  GenNKeyN [label="{GenNKeyN |{AuthorKeyPair|NetworkKeyPair}}"]
  
  MasterSeed->GenSeed0
  MasterSeed->GenSeed1
  MasterSeed->GenSeedN
  MasterSeed->RevSeed
  
    RevSeed->RevKey0
    RevSeed->RevKey1
    RevSeed->RevKeyN

    GenSeed0->Gen0Key0
    GenSeed0->Gen0Key1
    GenSeed0->Gen0KeyN
    
    GenSeed1->Gen1Key0
    GenSeed1->Gen1Key1
    GenSeed1->Gen1KeyN
    
    GenSeedN->GenNKey0
    GenSeedN->GenNKey1
    GenSeedN->GenNKeyN

}