# nKode Tutorial

## nKode Keypad

- nKode keypad contains keys
- Each key has icons
- Each icon belongs to a set and has an index value associated with it
- The position within the key is the set value
- When attributes are shuffled, they'll always remain in the same position within the key
        (note: the set value can be obuscated from the client but we find it helpful to quickly find the attribute)

## nKode Enrollment 

- user sets then confirms their nKode
- Set and Confirm are dipersion of each other and allow the server to infer the users nKode
- the users login has additional icons added to each to key to make it dispersion resistant
- After the user as selected their nKode through the set and confirms,
    the server can infer the users selection since each key selection will only have one icons in common.
- The users nKode is enciphered, salted and hashed.

## Dispersion

- Two keypads are dispersion of each other if:
Kp1: Keypad 1
Kp2: Keypad 2

for each key1 in Kp1:
    for each key2 in Kp2:
        iconsIntersection(key1, key2) <= 1


## Dispersion Algo

- Convert a Keypad view into a matrix view
    - each row is key and each column is a set
- Fisher Yates the keys i.e. the rows in the matrix
- Fisher Yates an identity matrix equivalent to the number of keys
- The shuffled permutation is used to rotate the columns


## Dispersion Resistance

- Dispersion is only possible if {number of icons per key} <= {number keys in the keypad}
- If there are more icons per key than keys, it makes it difficult to phish for a users nkode


## Cipher Keys

#### attribute key

- randomly generated array of unsigned integars 
- array of length {numb of keys} * {number of attributes per key}  
- xored with ss-attr to give each user a unique

#### passcode key

- randomly generated array of unsigned integars
- array of length {max nKode length}
- xored with final user passcode

#### set key

- used to recover users nkode set values
- array of unsigned integars
- each elemenet in the array is a random number XOR'ed with the set value of the users nKode
- so `for set_key_i in user_set_key`
            `set_key_i = user_passcode_set_i ^ random_set_key_i`

#### mask key

- used to recover users nkode set values
- array of random unsigned integars

#### server-side attributes (ss-attr) and sets (ss-set)

- Each icon has a server side attribute.
- The icon and the ss-attr are indexed to the same place in an array. 
- The dispersion and shuffle operation are applied to the index array and the index array is applied to the icon and ss-attr 
- ss-attrs are randomly generated permutation of unsigned ints (or byte arrays of any length for extra security)

### Encipher and Hash nKode Passcode
passcode = index values of the selected icons infered in set/comfirm
user_attrs = arr_xor(ss_attr, user_attr_key)
passcode_attr = [user_attrs[idx] for idx in passcode]

ciphered_passcode = arr_xor(passcode_attr, user_passcode_key)

// optional sha256 if ciphered_passcode is more than 72 bytes
passcode_digest = sha256(ciphered_passcode)

hashed_passcode = bcrypt(passcode_digest)

### Enicphering nKode Set

nKode mask is used to recover the users nKode 
1. set_key_i = (set_rand_numb_i ^ set_val_i) 
2. mask_key_i = mask_rand_numb_i

passcode = index values of the selected icons infered in set/comfirm
// recall ss_set array is an order list
set_idx = get_set_value(passcode)
user_set_keys = [set_key[idx] for idx in set_idx]
user_set_vals = [ss_sets[idx] for idx in set_idx]
mask = arr_xor(user_set_val, user_set_keys, mask_key)

- mask_i = mask_key_i ^ padded_passcode_server_set_i ^ set_key_i
- mask_i = mask_rand_num_i ^ set_val_i ^ set_rand_numb_i ^ set_val_i
- mask_i = mask_rand_num_i ^ set_rand_numb_i # set_val_i is cancelled out

#### nKode Validation
// set_val_i = mask_i ^ set_key_i ^ mask_key_i 
// selected_keys the keys the user selects
recovered_set_vals = arr_xor(mask, set_key, mask_key)
user_keypad = get_user_keypad(username)

presumed_password = get_pressumed_passcode(user_key, selected_keys, recovered_set_val)

if is_valid_passcode(presumed_password, hashed_passcode)
    return LOGIN_SUCCESS
else
    return LOGIN_FAIL


## nKode Login Shuffle

- After a successful login, the users keypad is shuffled in a two step process:
    1. the keys are randomly shuffled
    2. half the sets are randomly shuffled
- We've found this works best for xyz reason and we're also working on simulations to find a probablity curve for number of overserveration before an adversery can crack an nkode


## nKode Login

- When a user request their nkode keypad, the server sends a list of svgs in the order they should be displayed
- The Gen2 demo implementation works a bit different it sends the svgs indexed in order from 0-total_numb_of_attr along with an index array for how the svgs should be ordered
    - this is a legacy from the gen 1 keypad but it helps to make the implemntation more concrete so we'll use this legacy 
- The frontend organized the svgs into keys and displays them.
- The user selects keys for their nkode and their key selection is sent back to the server for validation


## Preventing User Enumeration

- This isn't applied in the demo application
- We can prevent a threat actor from enumerating users.
    - if a valid email is entered into the login for a user that dne, we can create a ghost keypad and have it behave as if it were a real user.
    - if there are too many "failed nkode attempts" we lock the non-existing user out.
- We can prevent timing attacks by either mocking the real control flow or setting a 1 or 2 sec response delay from the time the login request was recieved thereby completely elimiating timing attacks 

## Renew
Renew changes user ciphers, user salt, ss_attr, and ss_set.
This is import in the event of a partial database hack or leak.
An admin or cron job can run the renew with any frequency (daily, weekly, monthly)
Users are aware of this process.
Nothing changes for them.

### Three Step Renew
Renew has three phases

1. Server-Side Attribute Renewal: ss_attr and ss_set values are replaced with new values
2. Intermdiate User Renewal: every user goes through an intermediate phase before full Renewal
3. Full User Renewal: The user's first successful login completes the renewal. User has gets new salt, and cipher

#### Server-Side Attribute Renewal

old_ss_attr, old_ss_set = get_ss_vals()
renew_ss_vals() // new randomly generated values
new_ss_attr, new_ss_set = get_ss_vals()

xor_ss_attr = arr_xor(old_ss_attr, new_ss_attr)
xor_ss_set = arr_xor(old_ss_set, new_ss_set)

#### Intermdiate User Renewal

all_users = get_all_users()
for user in all_users:
    user.renew = True // This flags the server to complete phase 3, full user renewal
    user.set_key = xor_lists(user.set_key, xor_ss_set) // recall user.set_key = rand_num ^ old_ss_set. this operation cancels out old_ss_set and replaces it with new_ss_set
    user.attribute_key = xor_lists(user.attribute_key, xor_ss_attr) // recall user.attribute_key ^ old_ss_attr are the user's nkode ss attributes so when we 

#### Full User Renewal

After a successful login user keys are reset as if the user was signing up for the first time