Difference between revisions of "Platform Team/Server Kit/sugar-server"
m (moved Sugar Server Kit/sugar-server to Platform Team/Server Kit/sugar-server: Move SSK to HSD) |
|||
(65 intermediate revisions by 3 users not shown) | |||
Line 5: | Line 5: | ||
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. | 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 a database to keep information about registered users or activated machines. The registry is file based, i.e., every item is kept in one file (in JSON notation) in the {{Code|<root-option>/home/registry}} directory. | |
− | + | There are two subdirectories, i.e., "tables": | |
− | |||
− | |||
− | + | * {{Code|users}}, for registered users, and | |
+ | * {{Code|machines}}, for machines that requested activation leases on bootstrap. | ||
− | + | Registry items might contain the following keys: | |
− | + | * {{Code|uid}}, user's identity got after registration on a server; | |
+ | * {{Code|machine_sn}}, serial number of hardware Sugar user is running on, e.g., serial number of a XO laptop; | ||
+ | * {{Code|machine_uuid}}, UUID value of hardware Sugar user is running on, e.g., UUID of a XO laptop; | ||
+ | * {{Code|pubkey}}, SSH public key, this is the exact line that needs to be placed as-is to {{Code|~/.ssh/authorized_keys}} file; note that OLPC XS operates with stripped version of public keys. | ||
− | + | == Services == | |
− | The resulting dictionary on success, | + | 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_Server_Kit/sugar-client|sugar-client]] with a [[Sugar_Server_Kit/Client_API|Client API]] it provides for clients, e.g., Sugar Shell. |
+ | |||
+ | If a particular service supports a [[wikipedia:Representational_state_transfer |RESTfull interface]], the HTTP server is started on {{Code|host}} with the {{Code|httpd-port}} port. The content of requests and replies is transferred using dictionaries in JSON notation. | ||
+ | |||
+ | The resulting dictionary on success, will contain predefined keys: | ||
* {{Code|success: OK}}; | * {{Code|success: OK}}; | ||
− | |||
− | |||
− | The resulting dictionary on | + | The resulting dictionary on failure, will contain: |
* {{Code|success: ERR}}; | * {{Code|success: ERR}}; | ||
− | * {{Code|error}} key with | + | * {{Code|error}}, error message. |
+ | |||
+ | === registry === | ||
+ | |||
+ | Provides Sugar users registration on a school server. After being registered, Sugar on user's side will set up interaction with a school server. See [[Sugar_Server_Kit/sugar-client|sugar-client]] project for details from the client point of view. | ||
+ | |||
+ | Interface: | ||
+ | |||
+ | POST '''/client/register''' | ||
+ | |||
+ | Process registration on a server. | ||
+ | |||
+ | The input dictionary, contains (see [[#User_identity_models|identity models]] section for additional details): | ||
+ | |||
+ | * {{Code|nickname}}, user's Sugar nick name; | ||
+ | * {{Code|machine_sn}}, machine's serial number, makes special sense only for XO anti-thief support and [[#Hardware_based_model|hardware based]] identity model, | ||
+ | * {{Code|machine_uuid}}, machine's UUID value, makes special sense only for XO anti-thief support, | ||
+ | * {{Code|pubkey}}, SSH public key passed as-is. | ||
+ | |||
+ | The resulting dictionary, contains: | ||
+ | |||
+ | * {{Code|uid}}, unique identity that needs to be used for further interaction with the server. | ||
+ | |||
+ | GET '''/client/status'''?uid=''UID'' | ||
+ | |||
+ | Get information about client's status on a server. | ||
+ | |||
+ | The resulting dictionary, contains: | ||
+ | |||
+ | * {{Code|registered}}, if {{Code|False}}, client needs to process registration; | ||
+ | * {{Code|jabber-url}}, if {{Code|registered}} is {{Code|True}}, Jabber server url; | ||
+ | * {{Code|backup-url}}, if {{Code|registered}} is {{Code|True}}, Rsync url to backup Journal to, needs to be used as-is. | ||
+ | * {{Code|pending-restore}}, is there a pending restore, i.e., if {{Code|True}}, during the registration on a server, there was an existing backup; any further, post registration, backup or restore will clean up the {{Code|pending-restore}} flag. | ||
+ | |||
+ | Requested uid might be NOT registered in cases like: | ||
+ | |||
+ | * registration was removed from the server, | ||
+ | * request was sent to a server that was not the same as where the uid was created, | ||
+ | * someone [[#Vulnerabilities|registered]] the same serial number. | ||
+ | |||
+ | Requirements: | ||
+ | |||
+ | * Current Sugar Shell code calls only XML-RPC method using the hard coded {{Code|http://schoolserver:8080/}} url. This restriction can be avoided using [[Sugar_Server_Kit/sugar-client|sugar-client]]. | ||
+ | |||
+ | Backwards compatibility: | ||
+ | |||
+ | ''dict'' '''register'''(''str'' machine_sn, ''str'' nickname, ''str'' machine_uuid, ''str'' pubkey) | ||
+ | |||
+ | To support OLPC's XS clients, RPC function to serve registration requests. The XML-RPC service will be listening to the {{Code|8080}} port on the {{Code|--host}} host. | ||
=== backup === | === backup === | ||
+ | |||
+ | Process backup and restore for students' Journals. The service accepts requests that clients send before starting the backup process. If server accepts requests, clients start Rsync'ing Journal data via SSH. The Rsync url needs to be obtained from a {{Code|/client/status}} request and be used without any modification on the client side, i.e., the process is fully server driven. | ||
+ | |||
+ | Users' backups are stored in the {{Code|<root-option>/home/backups/<UID's-last-two-chars>/<UID>}} directories. | ||
+ | |||
+ | Interface: | ||
+ | |||
+ | GET '''/client/backup'''?uid=''UID'' | ||
+ | |||
+ | Check if client can start transferring Journal files. | ||
+ | |||
+ | The resulting dictionary, contains: | ||
+ | |||
+ | * {{Code|accepted}}, if {{Code|True}}, clients can start backup process. | ||
+ | |||
+ | Requirements: | ||
+ | |||
+ | * The {{Code|root}} configuration option should point to the home directory of the system user that starts sugar-server process. This is needed because clients will SSH to this user to perform Rsync backups. | ||
+ | |||
+ | Backwards compatibility: | ||
+ | |||
+ | Note, this backup functionality is not compatible with client tools that work with OLPC XS. The problem is that these tools construct a backup url on the client side (using only the server host name from a backup url given after registration on the server) so relying that every client has its own system user on the server side. That doesn't work with this new backup functionality, where there is only one system user on the server side, and authorisation happens at the SSH level (using the {{Code|command}} option in {{Code|~/.ssh/authorized_keys}} file). | ||
=== activation === | === activation === | ||
+ | |||
+ | This service is intended to process anti-thief requests that XO laptops send to the server during the boot process. It is looking for pre-created leases using {{Code|<root-option>/share/leases/<SN's-last-two-chars>/<SN>}} paths. If there are no existing leases and the {{Code|delegation}} option is {{Code|True}}, it will ask the [[#keyring|keyring]] service to generate a new one using delegated leases. | ||
+ | |||
+ | Interface: | ||
+ | |||
+ | GET '''/client/lease'''?machine_sn=''MACHINE_SN'' | ||
+ | |||
+ | Get OLPC anti-thief lease for specified XO's serial number. | ||
+ | |||
+ | The resulting dictionary, contains: | ||
+ | |||
+ | * {{Code|lease}}, lease content | ||
+ | |||
+ | Requirements: | ||
+ | |||
+ | * Current XO's bootstrap code uses TCP interface, having the following numbers hard coded: | ||
+ | ** {{Code|host}} needs to be {{Code|172.18.0.1}}, | ||
+ | ** {{Code|activation-port}} needs to be {{Code|191}}, | ||
+ | ** XOs use {{Code|172.18.96.1}} as a gateway while connecting to {{Code|172.18.0.1}}. | ||
+ | |||
+ | Backwards compatibility: | ||
+ | |||
+ | Service is also listening to {{Code|--activation-port}} port on the {{Code|--host}} host to process TCP requests used by the XO's bootstrapping code. If sent data starts with a serial number, the service will reply with: | ||
+ | |||
+ | * {{Code|STOLEN}} text, if serial number is stated as stolen; | ||
+ | * lease content found for serial number; | ||
+ | * {{Code|UNKNOWN}} for errors. | ||
=== keyring === | === keyring === | ||
− | === | + | Keyring service is needed to work with the activation one. It signs delegated leases for activation requests if pre-existing leases weren't found. |
+ | |||
+ | Interface: | ||
+ | |||
+ | There is no public interface, the service is used internally by sugar-server. | ||
+ | |||
+ | == User identity models == | ||
+ | |||
+ | How sugar-server will identify users upon registration. | ||
+ | |||
+ | === Hardware based model === | ||
+ | |||
+ | The use case assumes: | ||
+ | |||
+ | * the hardware is intended to run only Sugar, | ||
+ | * it serves only one user, | ||
+ | * there is an existing practice within XO deployments with workflows that need to be preserved. | ||
+ | |||
+ | To process registration, users need to provide: | ||
+ | |||
+ | * valid SSH public key, | ||
+ | * valid machine serial number, i.e., a serial number that the school server is aware of, e.g., there is an activation lease. | ||
+ | |||
+ | After re-flashing an XO (with loosing private key), it is possible to re-register the user by uploading a new public key. See [[#Vulnerabilities|below]] for related vulnerability issues. | ||
+ | |||
+ | The following TODO needs to be implemented: | ||
+ | |||
+ | * Properly handle backups after hardware switching for the particular user. | ||
+ | * More reliable identity scheme that will avoid [[#Vulnerabilities|compromising users]]. | ||
+ | |||
+ | === SSH key based model === | ||
+ | |||
+ | This is a low level model, since the major feature is uploading an 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 not be affected by "re-flashing" issue), | ||
+ | * it might serve multiple users. | ||
+ | |||
+ | To process registration, users need to provide a | ||
+ | |||
+ | * valid SSH public key. | ||
+ | |||
+ | To always have access to already-uploaded-to-the-server data, people need to take care about securing their SSH key. This key can be found in the {{Code|~/.sugar/''<profile>''/owner.key}} file. | ||
+ | |||
+ | === Vulnerabilities === | ||
+ | |||
+ | How current implementations are bad. | ||
+ | |||
+ | '''Compromised users''' | ||
+ | |||
+ | Current implementation of [[#Hardware based model|hardware based]] identity model has a security issue that might be described with the following use case: | ||
+ | |||
+ | * an XO registered on a school server; | ||
+ | * processed several Journal backups there; | ||
+ | * got re-flashed and failed in keeping client side identities, like the Sugar profile private key; | ||
+ | * the XO wants to re-register to restore Journal content from a previous backup. But from the school server point of view, this request is a regular registration request from a new XO (which provides the same serial number that the existing registration uses). | ||
+ | |||
+ | Sugar-server will process these registrations assuming that the request was sent from an 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 a properly resolved {{Code|schoolserver}} host name. | |
− | + | Possible solutions: | |
− | * | + | * [[Sugar_Server_Kit/1.2/Todo#Avoid_compromised_school_servers|Switch to HTTPS]]. |
− | |||
== Configuration == | == Configuration == | ||
− | By default, configuration occurs based on several sources (sorted by | + | By default, configuration occurs based on several sources (sorted by order of application): |
* {{Code|/etc/sugar-server.conf}} system-wide configuration file, | * {{Code|/etc/sugar-server.conf}} system-wide configuration file, | ||
− | * {{Code|~/. | + | * {{Code|~/.config/sugar-server/config}} user-wide configuration file, |
* {{Code|sugar-server}}'s command-line arguments. | * {{Code|sugar-server}}'s command-line arguments. | ||
Line 63: | Line 219: | ||
sugar-server config | sugar-server config | ||
− | See [http://git.sugarlabs.org/server/templates/trees/master/ | + | See [http://git.sugarlabs.org/server/templates/trees/master/mace/sugar-server sugar-server-templates] sources for an example. |
== Getting involved == | == Getting involved == |
Latest revision as of 05:48, 21 March 2012
Summary
The core Sugar Server Kit component.
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 a database to keep information about registered users or activated machines. The registry is file based, i.e., every item is kept in one file (in JSON notation) in the <root-option>/home/registry
directory.
There are two subdirectories, i.e., "tables":
users
, for registered users, andmachines
, for machines that requested activation leases on bootstrap.
Registry items might contain the following keys:
uid
, user's identity got after registration on a server;machine_sn
, serial number of hardware Sugar user is running on, e.g., serial number of a XO laptop;machine_uuid
, UUID value of hardware Sugar user is running on, e.g., UUID 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 stripped 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 a particular service supports a RESTfull interface, the HTTP server is started on host
with the httpd-port
port. The content of requests and replies is transferred using dictionaries in JSON notation.
The resulting dictionary on success, will contain predefined keys:
success: OK
;
The resulting dictionary on failure, will contain:
success: ERR
;error
, error message.
registry
Provides Sugar users registration on a school server. After being registered, Sugar on user's side will set up interaction with a school server. See sugar-client project for details from the client point of view.
Interface:
POST /client/register
Process registration on a server.
The input dictionary, contains (see identity models section for additional details):
nickname
, user's Sugar nick name;machine_sn
, machine's serial number, makes special sense only for XO anti-thief support and hardware based identity model,machine_uuid
, machine's UUID value, makes special sense only for XO anti-thief support,pubkey
, SSH public key passed as-is.
The resulting dictionary, contains:
uid
, unique identity that needs to be used for further interaction with the server.
GET /client/status?uid=UID
Get information about client's status on a server.
The resulting dictionary, contains:
registered
, ifFalse
, client needs to process registration;jabber-url
, ifregistered
isTrue
, Jabber server url;backup-url
, ifregistered
isTrue
, Rsync url to backup Journal to, needs to be used as-is.pending-restore
, is there a pending restore, i.e., ifTrue
, during the registration on a server, there was an existing backup; any further, post registration, backup or restore will clean up thepending-restore
flag.
Requested uid might be NOT registered in cases like:
- registration was removed from the server,
- request was sent to a server that was not the same as where the uid was created,
- someone registered the same serial number.
Requirements:
- Current Sugar Shell code calls only XML-RPC method using the hard coded
http://schoolserver:8080/
url. This restriction can be avoided using sugar-client.
Backwards compatibility:
dict register(str machine_sn, str nickname, str machine_uuid, str pubkey)
To support OLPC's XS clients, RPC function to serve registration requests. The XML-RPC service will be listening to the 8080
port on the --host
host.
backup
Process backup and restore for students' Journals. The service accepts requests that clients send before starting the backup process. If server accepts requests, clients start Rsync'ing Journal data via SSH. The Rsync url needs to be obtained from a /client/status
request and be used without any modification on the client side, i.e., the process is fully server driven.
Users' backups are stored in the <root-option>/home/backups/<UID's-last-two-chars>/<UID>
directories.
Interface:
GET /client/backup?uid=UID
Check if client can start transferring Journal files.
The resulting dictionary, contains:
accepted
, ifTrue
, clients can start backup process.
Requirements:
- The
root
configuration option should point to the home directory of the system user that starts sugar-server process. This is needed because clients will SSH to this user to perform Rsync backups.
Backwards compatibility:
Note, this backup functionality is not compatible with client tools that work with OLPC XS. The problem is that these tools construct a backup url on the client side (using only the server host name from a backup url given after registration on the server) so relying that every client has its own system user on the server side. That doesn't work with this new backup functionality, where there is only one system user on the server side, and authorisation happens at the SSH level (using the command
option in ~/.ssh/authorized_keys
file).
activation
This service is intended to process anti-thief requests that XO laptops send to the server during the boot process. It is looking for pre-created leases using <root-option>/share/leases/<SN's-last-two-chars>/<SN>
paths. If there are no existing leases and the delegation
option is True
, it will ask the keyring service to generate a new one using delegated leases.
Interface:
GET /client/lease?machine_sn=MACHINE_SN
Get OLPC anti-thief lease for specified XO's serial number.
The resulting dictionary, contains:
lease
, lease content
Requirements:
- Current XO's bootstrap code uses TCP interface, having the following numbers hard coded:
host
needs to be172.18.0.1
,activation-port
needs to be191
,- XOs use
172.18.96.1
as a gateway while connecting to172.18.0.1
.
Backwards compatibility:
Service is also listening to --activation-port
port on the --host
host to process TCP requests used by the XO's bootstrapping code. If sent data starts with a 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 the activation one. It signs delegated leases for activation requests if pre-existing leases weren't found.
Interface:
There is no public interface, the service is used internally by sugar-server.
User identity models
How sugar-server will identify users upon registration.
Hardware based model
The use case assumes:
- the hardware is intended to run only Sugar,
- it serves only one user,
- there is an existing practice within XO deployments with workflows that need to be preserved.
To process registration, users need to provide:
- valid SSH public key,
- valid machine serial number, i.e., a serial number that the school server is aware of, e.g., there is an activation lease.
After re-flashing an XO (with loosing private key), it is possible to re-register the user by uploading a new public key. See below for related vulnerability issues.
The following TODO needs to be implemented:
- Properly handle backups after hardware switching for the particular user.
- More reliable identity scheme that will avoid compromising users.
SSH key based model
This is a low level model, since the major feature is uploading an 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 not be affected by "re-flashing" issue),
- it might serve multiple users.
To process registration, users need to provide a
- valid SSH public key.
To always have access to already-uploaded-to-the-server data, people need to take care about securing their SSH key. This key can be found in the ~/.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 use case:
- an XO registered on a school server;
- processed several Journal backups there;
- got re-flashed and failed in keeping client side identities, like the Sugar profile private key;
- the XO wants to re-register to restore Journal content from a previous backup. But from the school server point of view, this request is a regular registration request from a new XO (which provides the same serial number that the existing registration uses).
Sugar-server will process these registrations assuming that the request was sent from an 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 a properly resolved schoolserver
host name.
Possible solutions:
Configuration
By default, configuration occurs based on several sources (sorted by order of application):
/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.