This is a handy presentation:
www.jopera.org/files/SOA2009-REST-Composition.pdf
"Techniques for Composing Rest services"
I'll post some notes on service composition in crux shortly.
To activate protected access modes for a device, a user may have to supply a password. This post gets into the protocol of how that password is used to authenticate requests.
server-side mode database
Each access mode supported by a device has a short nickname and a longer display name. Some modes are protected by password. Associated with each mode is a list of permissions.
- nickname is a unique (on this device) ID for the mode, used in the web api and sometimes for human display. Example: "prog".
- display name is a descriptive name for the mode, suitable for use in displays for human readers. Example: "program mode".
- password, if present, is secret string needed to access the mode. Cryptographic hashes of passwords are stored on a crux instance server, not the passwords themselves.
- permissions is a list of URIs (see below) describing the device capabilities that can and can not be accessed from the mode
server-side nonce buffer
At regular intervals (say, once or a few times per hour), crux servers generate a random string -- the server nonce -- which is used in crux authentication protocols. These nonces are retained (buffered) for an amount of time equal to the longest permitted authentication session, and then they're discarded.
server-side blacklist buffer
The server-side blacklist buffer contains a list of recently cancelled (aka "logged out") session ids. Session ids (see the "abstract protocol", below) are put in the blacklist buffer upon being canceled and remain the buffer for as long as their server nonces are valid. The presence of a session id in the blacklist buffer prevents further use of that id, in spite of the id still having a current server nonce.
abstract protocol
Every (non-error) response from a crux instance server includes the most recently created server nonce. This nonce is available to the client for the authentication protocol. The protocol can be abstractly described this way:
mode_name = the short nickname of the mode
server_nonce = a server side nonce, recently returned from the deviceclient_nonce = a nonce generated by the client, for a new session. Ideally, the client nonce is globally unique, hard to guess, and unlikely to be re-used. In the quite possible event that two clients both know the password, both use the same mode, and both use the same server nonce -- it is only the client nonce that will distinguish their sessions. If they use the same client nonce, they will share a single session.password_plain = the plaintext password, only known to the cilent sidepassword_hash = hash (password_plain) ~~~ the client computes this value and and the server already has it stored in the mode database. It is not transmitted directly during authentication.credential_plaintext = <password_hash, client_nonce, server_nonce>
~~~ both client and server compute thiscredential_hash = hash (credential_plaintext)
session_id = <mode_name, client_nonce, server_nonce>
cert = <session_id, credential_hash>
When entering a protected mode, a client has a previously received server nonce and generates a new client nonce. The password is supplied by the user. The client computes a cert and passes that with future requests to authenticate its access to the mode.
The server treats as invalid any session id whose server_nonce is not currently in the server's nonce buffer.
The server treats as invalid any server id that is currently found in the server's blacklist buffer. If the number of blacklisted session ids for the same mode and same server nonce exceeds a device-specific threshold, then all server ids with that mode and server nonce (regardless of client nonce) are considered invalid.
Given a session id, not blacklisted, with a current server nonce, the server re-computes cert for itself, comparing that to the value sent by the client. If the values match, access to the mode is permitted and the mode's list of permissions applies to the request.
no session-specific server state
This is the buried lead:
Session management in the crux API is stateless in the sense that instance servers maintain no session-specific state. The server's session-related state is limited to:
- the mode database
- the server nonce buffer
- the server blacklist buffer
Mode database entries and nonce buffer entries are shared by similarly timed requests for the same model. Neither contains any mode-specific data.
Canceling a session can trigger a new entry in the blacklist buffer -- which is in some sense session-specific data -- but canceling a session won't always do so. They catch is found in this rule from the protocol description given above:
If the number of blacklisted session ids for the same mode and same server nonce exceeds a device-specific threshold, then all server ids with that mode and server nonce (regardless of client nonce) are considered invalid.
Because of that rule, cancelling a session doesn't always add any new data to the blacklist buffer. In fact, the maximum number of entries in the blacklist buffer is governed by a formula:
n_nonces := size of the server-side nonce buffer
n_modes := number of access modes available on the device
threshold := blacklist max-out limit for a given nonce and mode id
max_blacklist := n_nonces * n_modes * threshold
To make less likely the unwanted display or modification of sensitive device state, crux uses a system of authorization and authentication between browser and server.
background
A crux instance provides a web API for the state of some personal computing device. Users typically access their personal crux instances through standard web browsers.
access modes
A crux "access mode" is a set of permissions against which a request is judged. A client sends a request in a given access mode such as by returning an authentication cookie for that mode. Whether or not a request succeeds may depend on the permissions assigned to that access mode.
access mode example: Imagine a tablet interface (a web browser) to a crux digital video recorder (DVR). If the client is making requests in "user" mode, the tablet can be used to edit the recording schedule. If the client is using "lock" mode, schedule changes are prevented. If the client is sending requests in "root" access mode, the user can change the password used to exit "lock" mode.
A device might have a fixed number of built-in access modes or it might allow users to create new customized access modes.
Every access mode on a crux device is assigned a short-hand name, like "user" or "lock", as well as a display name, like "user mode". Invoking a mode from a client may require the user to supply a password, or similarly authenticate.
comparing access modes and user accounts: crux access modes are similar to the concept of a user account on other platforms. Both have symbolic and full names. Both may be password protected. Both user accounts and access modes correspond to a list of permissions on a given system. That is about where the similarity ends, though. For example, we usually think of user accounts and actual users as being in a roughly 1:1 relationship most of the time but with access modes, that isn't the case. Everyone who uses a given device might share one or a few access modes; one user of a device might have many access modes. Another example: user accounts on other platforms often correspond directly to email accounts or to "home directories" or similar concepts. In contrast, crux access modes have neither of those things.
sessions
When a user gives a password or otherwise authenticates to enter some protected access mode, that starts a new session. In a typical application the user's client browser will remain in that same session, and hence that same access mode, at least for a period of time.
A session is the context in which you don't have to retype a password. In crux, new sessions are created when a user activates some password-protected access mode on a device.
If left idle, a crux session might expire. Or an interface might permit a user to explicitly close a session. In either case, to resume using that access mode the user would have to re-supply the password and thus begin a new session.
Users form mental models of the state of various personal devices. For example, they have a sense of what contact numbers are stored in their cell phone, what settings are stored in their DVR, which files are on which computers, and so forth.
One reason to have the concept of a "crux instance" is to give users a single, unified concept of "state" when it comes to their personal computing devices.
To be sure, the "state" of a DVR (say, which programs are set to be recorded) and the "state" of a cell phone (say, a list of numbers on speed-dial) are different kinds of data, used in different ways.
Still, the two kinds of state can usefully have something in common. For example, it could be convenient if the state of the DVR and of the cell phone could be backed up and restored using a single, common mechanism. Or if a user wants to bypass the software on either device, and inspect or modify the state of the system directly, it could be convenient if both devices provided the same interface for this.
From a programmatic point of view, all crux instances, regardless of what kind of device they are on, offer a common web API for examining and modifying the state of that device. Programmers can write tools that examine and modify the state of devices in a generic way.
For users, the semantics of the crux state API coincide with the user's conceptual model of what the management of state has in common across all of their devices.
A crux instance is a "personal web service", meaning:
- Each crux instance is a specific web server, with its own URL.
- Usually, a crux instance is accessed only by a small number of users.
- The individual owner(s) of an instance is(are) usually the main person(s) to access that server.
- Crux instances are not usually "on the net" in the usual way. They are (typically) not public servers; they are servers on private networks.
A "crux device" is a tangible personal computing device (perhaps a "workstation", "laptop", or "mobile" device) that comprises at least one crux instance local to that device, along with a standard web browser that can access all crux instances on the same device.
Here are three examples to make this a bit more concrete:
Example 1: Mobile Crux Device Imagine a handheld portable computing and communication device -- such as a cell phone or tablet -- whose user interface takes the form of a standard web browser, and whose operating system is accessed entirely via HTTP requests to a crux instance web server running locally on that same device.
Example 2: $20 personal home computer Imagine a "wall-wart"-style of hyper-inexpensive computer that comes with a wireless keyboard and mouse and can connect to typical home AV systems. When booted, the computer presents a browser-based interface and all of the system's operating system functionality can be accessed via a crux instance web server running on the device.
Example 3: Crux components Imagine a home "AV" system containing multiple "active" components. In a crux world it would be sensible for each component (say, each DVR and each "intelligent" amplifier) to host its own crux instance. That is to say, each active component would provide a web API to its functionality to the owner's local network. Because each component is locally accessible via HTTP, a single physical device (say, a tablet-form computer) can host a single browser, providing an interface to the several crux instances in the AV system.
