Flow - HackMD

# Flow ## Section 1 - Storages Entities that can act as share storages 1. Secure storage 2. Service provider 3. Pen&paper 4. Native application (desktop) 5. 2nd phone 6. Social recovery (friend's phone) ## Section 2 - 2/2 ### Sign up / Setup User sign up to service provider and generated private key for wallet. https://app.diagrams.net/#G1Kcwf3sgMrEfyG53i9BX8RQfRQOMeESrX https://drive.google.com/file/d/1Kcwf3sgMrEfyG53i9BX8RQfRQOMeESrX/view?usp=sharing ![](https://i.imgur.com/3Q9pEa0.png) ``` 1. ~~performOAuth( OAuth params ) returns (jwt json) :- Interacts with the OAuth Provider, performs the authentication and gets back a JWT token~~ 2. initializeECDH() returns (gk1 string) :- Triggers creation of ephemeral key K1 on secure process and the corresponding public keys gk1 4. ~~spaAuthentication(JWT string, gk1 string) returns (gk2 string) :- Authenticate JWT and return gk2 in response to the ECDH communication channel.~~ 5. setupECDH(gk2 string) returns void :- Imports gk2 into the secure process and establish ECDH 6. generatePrivateKey() returns (publicKey string) :- Causes the secure process to generate a private key and store and returns the publicKey 7. initializeTkey(publicKey string) returns ([sharesPubKey]: string) :- Returns the public key of shares created 8. UNTRUSTED_exportShare(publicKey string) returns (share: string) :- Export share over ECDH. Only 1 share can be exported in such manner and this can be enforced on secure proess level.` ``` ### login Case 1. - Assumption device has shareA and only require 1 more share to reconstruct private key https://app.diagrams.net/#G1ptOX90r_5jpNM5je9t9tsP5v7qXmh8Am https://drive.google.com/file/d/1ptOX90r_5jpNM5je9t9tsP5v7qXmh8Am/view?usp=sharing ![](https://i.imgur.com/la8uUlD.png) 1. setupECDH() 2. importShare(encShare: string): returns (bool) 3. reconstructKey() ## Section 3 - 2/3 ### Setup - shareA (secure process) + Service Provider + shareC (pen & paper) - shareA (secure process) + Service Provider + shareC (native application) - shareA (secure process) + Service Provider + shareC (2nd Phone) make setupECDH implicit and explicit. It is upon SPA to use implicit vs explicit explicit is inteded for device backup so that it can show verification code that matched with backup device 3.1 - export backup share to native application https://app.diagrams.net/#G1_0l1a7fv5Nxhp6CT1vD3AD9UOXB1-Pnc https://drive.google.com/file/d/1_0l1a7fv5Nxhp6CT1vD3AD9UOXB1-Pnc/view?usp=sharing 1. initializeECDH() 2. setupECDH() 3. displayECDH(gk2: string) returns (x:string => secureUI(x)) 4. generateNewShare(publickey: string) returns ([shareIndex]: string) 3. exportShare(publicKey: string) return (encShare bool) 4. getSetMetadata() 3.1a - device to device ( Saga phone ) https://app.diagrams.net/#G1F3Vr687fl7NEW_bw-bZufpW0IDaJVr2v https://drive.google.com/file/d/1F3Vr687fl7NEW_bw-bZufpW0IDaJVr2v/view?usp=sharing Note: since we're spending a lot of effort to ensure usage on the secure process, should the specfication also attempt to restrict other receving/share holding native applications to be the same? 1. initializeECDH() 2. setupECDH() 3. addShare(publickey: string) returns ([shareIndex]: string) 4. exportShare(publicKey: string) returns (encShare bool) 5. getSetMetadata() 6. reconstuctKey() If so could potentially ensure this security via the service provider server, inbetween step 5 and 6 in 3.1 flow? 3.2 - export backup share to pen & paper https://app.diagrams.net/#G1BUm9xGc8Y-hiHFdmot9WKV5kA-ZcaXIF https://drive.google.com/file/d/1BUm9xGc8Y-hiHFdmot9WKV5kA-ZcaXIF/view?usp=sharing 1. addShare(publickey: string) returns ([shareIndex]: string) 2. displayShare(publickey: string) return (secureUI): Show the share on secure UI ### 2/3 login For 2/3 login, we could have scenario below : 1. ShareA + ShareB (Service Provider)-> same as 2/2 login https://app.diagrams.net/#G1ptOX90r_5jpNM5je9t9tsP5v7qXmh8Am ``` 1. setupECDH() 2. UNTRUSTED_importShare(encShare: string): returns (bool) 3. reconstructKey() ``` 2. ShareA + ShareC (pen & paper) https://app.diagrams.net/#G1WaBCFKMyzX5zsWYNql01WUqDmq2wL5vG https://drive.google.com/file/d/1WaBCFKMyzX5zsWYNql01WUqDmq2wL5vG/view?usp=sharing ``` 1. inputShareViaSecureUI(shareIndex: string): return (bool) 2. recontructKey(): reutrns (bool) ``` 3. ShareA + ShareC (backup-share from native application) https://app.diagrams.net/#G1Aql89msB9M7RM3WqujujzXP-YqnfF1Lf https://drive.google.com/file/d/1Aql89msB9M7RM3WqujujzXP-YqnfF1Lf/view?usp=sharing ``` 1. setupECDH() 2. displayECDH(gk2: string) returns (x:string => secureUI(x)) 2. importShare(encShare: string): returns (bool) 3. reconstructKey() ``` 4. ShareB + ShareC (2nd phone) -> same as case 1 https://app.diagrams.net/#G1ptOX90r_5jpNM5je9t9tsP5v7qXmh8Am For case 6,7 below, login to Service Provider (case1/4) is performed prior importing share C - flow 5. ShareB + ShareC (pen & paper) https://app.diagrams.net/#G1WaBCFKMyzX5zsWYNql01WUqDmq2wL5vG https://drive.google.com/file/d/1WaBCFKMyzX5zsWYNql01WUqDmq2wL5vG/view?usp=sharing ``` 1. setupECDH() 2. importShare(encShare: string): returns (bool) 3. inputShareViaSecureUI(shareIndex: string) returns (bool) 4. reconstructKey() ``` 6. ShareB + ShareC (backup share to native application) https://app.diagrams.net/#G1Aql89msB9M7RM3WqujujzXP-YqnfF1Lf https://drive.google.com/file/d/1Aql89msB9M7RM3WqujujzXP-YqnfF1Lf/view?usp=sharing ``` 1. setupECDH() - *2 2. importShare(encShare: string): returns (bool) - *2 3. displayECDH(gk2: string) returns (x:string => secureUI(x)) 4. reconstructKey() ``` 7. ShareA + ShareC (2nd phone) -> not possible as we do not allow export of share A However, we do allow user to backup to a new phone which is similar to case 3.1a which will need to login into Service Provider/ restore with pen&paper share https://app.diagrams.net/#G1RThjnh7_ks04sjhXYgYV01YUvfVOP3u1 https://drive.google.com/file/d/1RThjnh7_ks04sjhXYgYV01YUvfVOP3u1/view?usp=sharing 8. ShareB + ShareC (native application) -> not applicable to secure proccess https://app.diagrams.net/#G1ckIqtqNEE6QgnuWEWtLZEucnxfgFHb8q https://drive.google.com/file/d/1ckIqtqNEE6QgnuWEWtLZEucnxfgFHb8q/view?usp=sharing ``` no APIs ``` ## Secure process Functions to be implemented ``` ## Secure Process core functions to be implemented lagrangeInterpolation() // reconstruction refreshShares() encryptMetadata() decryptMetadata() ``` APIs Interactions Between Processes ``` ## Application process to Secure Process API initializeECDH() // create ephmeral key setupECDH() // setup gab // is this always followed by importShare()?? No exportShare() importShare() generatePrivateKey() initializeTkey() generateNewShare() reconstructKey() removeShare() ## Secure Process to Secure UI API displayECDHViaSecureUI() // useful in device confirmation importShareViaSecureUI() exportShareViaSecureUI() ## Other potential implicit APIs b/w AP and SP (does not need user interaction) getSetEncryptedMetadata() ``` Descriptions ``` ## Application process to Secure Process initializeECDH() // Triggers creation of ephemeral key K1 on secure process and the corresponding public keys gk1 setupECDH() // setup gab // is this always followed by importShare()?? N // Imports gk2 (public key derived from ephimeral key K2 generated on Service Provider) into the secure process and establish ECDH exportShare() // Export share over the established ECDH channel importShare() // Import the ECDH share from SPA to the secure process generatePrivateKey() initializeTkey() generateNewShare() reconstructKey() removeShare() refreshShares() // why should this be ever exposed ?? ## Secure Process to Secure UI displayECDHViaSecureUI() // useful in device confirmation importShareViaSecureUI() // User to input a share on the secure UI which is then imported over to the secure process exportShareViaSecureUI() // Exporting a share on the secure UI for user opting for manual backups ## Potential implicit APIs b/w AP and SP getSetEncryptedMetadata() // Getter + Setter method for metadata related operations. Called on any updates to shares. ``` ## Section 4 - 2/n 2/3 can be extend to higher threshold using any combination of storage entities defined in section 1 ## Section 5 ### Remove Share m/n can be reduce to m/(n-1) by remove a share limitation: - cannot remove shareA - cannot remove service provider share (shareB) 1: lost/stolen/exposed storage entity https://app.diagrams.net/#G1dmmQIjuA8MkHB8yOr5yIu2r48RM9VOqi ### Fetch latest Share Removing shares would cause share refresh. Offline device might not able to update to the latest share getMetadata() -> get metadata from tkey setMetadata() -> update secure process's tkey metadata https://app.diagrams.net/#G1X9nMatvG3KtzRsDDrmH0N62jEubT_lNG # Appendix setupECDH() Share(ecdh gb ) -> Trigger Secure UI confirmation to send to Device getMetadata() -> required to update metadata server addBackupShareUiInput() -> Trigger Secure UI for user input # setupECDH() importECDHShare(ECDH share) shareSign(ECDH share) -> need for retrieve metadata from metadata server # user input inputShare() -> trigger secure ui for user to key in reconstructPrivateKey() https://drive.google.com/file/d/1WaBCFKMyzX5zsWYNql01WUqDmq2wL5vG/view?usp=sharing Case 1b - Get BackupSare from user device # device 2 device setupECDH() importECDHShare(ECDH share)-> trigger secure ui confirm page to import from device reconstructPrivateKey https://app.diagrams.net/#G1RThjnh7_ks04sjhXYgYV01YUvfVOP3u1 ### Others // Tkey providerLogin( jwt ) { Pointer = setupEDSA() } getMetadata() -> { metadata, *encryptedShare} setMetadata( { metadata, *encryptedShare} ) *encryptedShare is applicable during refresh share, and update offline device removeShare() -> Trigger Secure UI confirmation of remove device -> reconstruce curve, updateMetadata getMetadata() - need to update to metadata server ## // Secure process Common APIs ``` initializeECDH() setupECDH() is this always followed by importShare()?? N exportShare() ``` setupECDH() : -> sharePointer setupECDH_send ( sharePointer) shareVerify(sharePointer, signedMessage) shareSign(sharePointer, message ) -> signedMessage exportShare(pointer, options) -> secure ui / ESDA exportEncryptedShare( pointer1, pointer2) -> encryptedShare //??? ** risk if shareDecrypt is available importEncryptedShare ( EncryptedShare, pointer ) -> pointer importShare( sharePrivateKey) -> pointer reconstructPrivateKey ( curveMetadata, [ …sharePointers] ) -> pointer (to PrivateKey) reconstructCurve ( curveMetadata, privateKey pointer) -> { Metadata, sharePointer[] } // *Disable Encrypt Decrypt for more secure enviroment shareDecrypt(sharePointer, encryptedMessage) shareEncrypt(sharePointer , message )