User Enrollment Protocol

This page presents the protocol for user account creation.

Requesting a Username

In the first step, a GET request is sent to /users?username. The server will give back a previously-unused username which will be valid for exactly five minutes.

Making an Account

An account consists solely of a username (handle) and password. Thus, the device should send the following as a JSON payload to /users:

{
  "handle": "string",
  "password": "string",
}

Note that this password is sent in the clear; as such, this must happen over TLS.

If successful, the server will respond with an HTTP 204 CREATED; otherwise, it will respond with 403 FORBIDDEN.

This page details the process for account creation. I'm assuming that accounts will be generated exclusively on the server, although we could make a custom messaging protocol to do this natively from device. I just figured that, like a lot of stuff, the initial account generation will take place through a webform on the server and then someone would have to log into their client device after.

Steps to Create an Account on the Textric Server

1. User provides prospective username. Goto 2.
2. Server check if username already exists in network. If YES, goto 1. Else, goto 3.
3. User provides and confirms password. Goto 4. [Implicit check in the webform that passwords match and meet password criteria.]
4. Server generates random salt, stores in a temporary variable. Goto 5.
5. Server hashes salt and password. Goto 6.
6. User optionally provides their name. Goto 7.
7. Server inserts record of username, salt, hashed password, optional name, and timestamp into users table. Goto 8.
8. User has a new account! Yay.

Unresolved issue: What if two people are trying to register the same username at the same time? I think you could enter a temporary entry into the users table, or perhaps have a hash set of active registration prospects (since presumably that would be small) and check that too. So basically, step 2 above would become:

2.a. Check if username is in users table. If YES, goto 1. Else, goto 2.b.
2.b. Check if username is in actively registering users set. If YES, goto 1. Else, goto 2.c.
2.c. Insert username into actively registering users set. goto 3. [This basically creates a mutex lock on the username.]

Additionally, there would be the following set inserted between 7 and 8 in this construct:

7.b. Server removes username from registering users set.

Thoughts about information storage

I'm envisioning we will need a few tables to keep track of user/device info. See below.

Table name	Table purpose	Table fields	Notes
users	Maintain list of all usernames and some master data about them.	username, salted_password_hash, master_salt, account_creation_date, name	This table will be the master arbiter of whether a username is available. Name field is optional.
devices	Maintain list of devices that are authenticated	device_id, username, device_hash, device_salt, last_seen	Device identifier is some unique identifier to the device (perhaps hashed MAC address). Username is foreign key to users table. device_hash is hash of salted_password_hash for user with device_salt. last_seen is the last time a device authenticated, for use in periodically deauthenticating inactive devices.