Platform Team/Server Kit/sugar-server

Summary

The singular program requires only Python, and obvious dependencies like coreutils, to allow all its services to function properly. It provides basic sugar related services, and uses one CLI tool to manage all its functionality.

Functionality

Registry

During the sugar-server work, all its components have access to a registry, an analog of database to keep information about registered users or activated machines. The registry is file based, i.e., every item is being kept in one file (in JSON notation) in registry-dir directory.

There are two subdirectories, i.e., "tables":

users, for registered users, and
machines, for machines that requested activation leases on bootstrap.

Registry items might contains the following keys:

uuid, user's identity got after registration on a server;
serial, serial number of hardware Sugar user is running on, e.g., serial number of a XO laptop;
pubkey, SSH public key, this is the exact line that needs to be placed as-is to ~/.ssh/authorized_keys file; note that OLPC XS operates with striped version of public keys.

Services

The list of services that sugar-server provides. Each service has a described interface to understand how it interact with clients. The counterpart for these interfaces is the sugar-client with a Client API it provides for clients, e.g., Sugar Shell.

If particular service supports RESTfull interface, the HTTP server is started on host with httpd-port port. The content of requests and replies is being transfered using dictionaries in JSON notation.

The resulting dictionary on success, will contain predefined keys:

success: OK;

The resulting dictionary on fails, will contain:

success: ERR;
error, error message.

id

Provide Sugar users registration on a school server. After being registered, Sugar on users side will setup interaction with a school server. See sugar-client project for details from client point of view.

Interface:

GET /client/status?uuid=UUID

Get information about client's status on a server.

The resulting dictionary, contains:

registered, if False, client needs to process [re]registration.

POST /client/register

Process registration on the server.

The input dictionary, contains (see identity models section for additional details):

nickname
serial
pubkey

The resulting dictionary, contains:

config a dictionary of values that are mapped 1:1 as configuration options of the sugar-client utility. See sugar-client's configuration for details;
OLPC XS backwards compatibility keys that are not being processed by sugar-client: backupurl, jabberserver, backuppath.

Requirements:

Current Sugar Shell code calls only XML-RPC method suing hard coded http://schoolserver:8080/ url. This restriction can be avoided using sugar-client.

Backward compatibility:

dict register(str serial, str nickname, str uuid, str pubkey)

To support OLPC's XS clients, RPC function to serve registration requests. The resulting data is the same as for RESTfull registration interface. The XML-RPM service will be listening 8080 port on the --host host.

backup

Process backup and restore for students' Journals. The service is accepting RESTfull requests that clients send before starting backup process. If server accepts requests, clients start Rsync'ing Journal data via SSH. The Rsync url needs to be gotten while registration via Id service and will be used without any modification on the client side, i.e., the process is fully server driven.

Interface:

GET /client/backup?uuid=UUID

Check if client can start transfering Journal files using.

The resulting dictionary, contains:

accepted, if True, clients can start backup process.

Requirements:

The root configuration option should point to the home directory of system user that starts sugar-server process. That needs because clients will SSH to this user to do Rsync backups.

Backward compatibility:

Note, this backup functionality does not compatible with client tools that work with OLPC XS. The problem is that these tools construct backup url on a client side (using only server host name from backup url given after registration on a server) with relying that every client has its own system user on a server side. That doesn't work with new backup functionality where there is only one system user on a server side and authorisation happens on SSH level (using command option in ~/.ssh/authorized_keys file).

activation

This service is intended to process anti-thief requests XO laptops send to the server during the boot process.

Interface:

GET /client/lease?serial=SERIAL

Get OLPC anti-thief lease for specified XO's serial number.o

The resulting dictionary, contains:

lease, lease content

Requirements:

Current XO's bootstrap code uses TCP interface with having the following numbers hard coded:
- host needs to be 172.18.0.1,
- activation-port needs to be 191,
- XOs use 172.18.96.1 as a gateway while connecting to 172.18.0.1.

Backward compatibility:

Service is also listening --activation-port port on the --host host to process TCP requests used by XO's bootstrapping code. If sent data starts from serial number, the service will reply with:

STOLEN text if serial number is stated as stolen;
lease content found for serial number;
UNKNOWN for errors.

keyring

Keyring service is needed to work with activation one. It signs delegated leases for activation requests if pre-existed leases weren't found.

Interface:

There is no public interface, the service is being used internally by sugar-server.

User identity models

How sugar-server will identify users while registration.

Hardware based model

The usecase assumes:

the hardware is intended to run only Sugar,
it serves only one user,
there is existing practice within XO deployments with workflows that need to be preserved.

To process registration, users need to provide:

valid SSH public key,
valid serial number, i.e., serial number that school server is aware about, e.g., there is an activation lease.

After re-flashing a XO (with loosing private key), it is possible to re-register user with uploading new public key. See below for related vulnerability issues.

The following TODO needs to be implemented:

Properly handle backups after switch hardware for particular user.

SSH key based model

This is a low level model, since the major purpose is uploading SSH public key to the server. This model might be useful in cases like:

the hardware is intended to run not only Sugar (thus, might be not affected by "re-flashing" issue),
it might serve multiple users.

To process registration, users need to provide:

valid SSH public key.

To have all-time access to already uploaded to the server data, people need to take care about keeping SSH key. This key can be found in ~/.sugar/<profile>/owner.key file.

Vulnerabilities

How current implementations are bad.

Compromised users

Current implementation of hardware based identity model has a security issue that might be described with the following usecase:

a XO registered on a school server;
processed several Journal backups there;
got re-flashed with not keeping client side identities, like Sugar profile private key;
the XO wants to restore Journal content from previous backups, but from school server point of view, it is regular registration request from new XO that provides the same serial number that existing registration uses.

Sugar-server will process these registrations assuming that the request was sent from a XO that has exactly the same serial number that was provided with the request.

Compromised servers

Both identity models might process registration on fake servers. The only thing clients need to start a registration, is properly resolved schoolserver host name.

Possible solutions:

Switch to HTTPS.

Configuration

By default, configuration occurs based on several sources (sorted by applied order):

/etc/sugar-server.conf system-wide configuration file,
~/.config/sugar-server/config user-wide configuration file,
sugar-server's command-line arguments.

Configuration files contain option names equal to command-line arguments. To get the current configuration, call:

sugar-server config

See sugar-server-templates sources for an example.

Getting involved

Report on bugs.
Read the HACKING file to know how to contribute with code.

Resources

Sources.