---
# System prepended metadata

title: Flow

---

# 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)

<br>

## 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()

<br>

## 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

<br>

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()
```

<br>

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

<br>

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.
 
 ```
 

<br>

## Section 4 - 2/n

2/3 can be extend to higher threshold using any combination of storage entities defined in section 1

<br>

## 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

<br>

### 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


<br>
<br>
<br>


# 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 )