Theft deterrence protocol: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Fix authentication and other issues with 'stolen' responses.)
Line 29: Line 29:
; version : the URI identifying the currently-running version on the laptop (or hash?)
; version : the URI identifying the currently-running version on the laptop (or hash?)
; stream : an opaque string identifying the "upgrade stream" to which the user has subscribed themself. Note that future upgrade servers may ignore this field in favor of central management
; stream : an opaque string identifying the "upgrade stream" to which the user has subscribed themself. Note that future upgrade servers may ignore this field in favor of central management
; nonce : an opaque string randomly generated by the client so as to be highly likely unique
; nonce
; delegated : an optional hint -- see the delegation response for more information
; delegated : an optional hint -- see the delegation response for more information


==Antitheft server response==
==Antitheft server response==
The response status code should be 200 if the response is accepted, 401 if the hashcash authentication failed, or 403 if the serial number requested has been reported stolen. We considered using a 305 response to indicate delegation, but such abuse of HTTP is probably a bad idea.
The response status code should be 200 if the response is accepted or 401 if the hashcash authentication failed.


Response if stolen:
Response format:
HTTP/1.1 403 Stolen
Content-Type: text/plain
This machine has been reported stolen.

We reserve the ability to use a different Content-Type and message body to communicate additional information regarding the machine, but at the moment this data in the response is ignored.

Normal response:
HTTP/1.1 200 OK
HTTP/1.1 200 OK
Content-Type: text/x-json
Content-Type: text/x-json
Line 56: Line 48:
; nonce: value nonce-data
; nonce: value nonce-data
: the nonce-data must match the nonce provided in the request exactly.
: the nonce-data must match the nonce provided in the request exactly.
; stolen: hash
: the stolen field, if present, contains a ascii hexadecimal-encoded sha256 hash. The hash is either of the string "<uuid>:<nonce>" or of "<uuid>:<nonce>:STOLEN".
; upgrade : value (hash, priority, hint)
; upgrade : value (hash, priority, hint)
: the hash identifies the new version to which we should upgrade
: the hash identifies the new version to which we should upgrade
Line 69: Line 63:


The only mandatory field in the response is 'nonce', which prevents replay attacks. If the 'lease' field is absent, then the server does not have a newer activation lease to give to the client. If the 'delegate' field is absent, then the response of this server is authoritative. If the 'upgrade' field is absent, the server judges the client's software version adequate for the time being. The options are not exclusive -- for example, the response might have both 'lease' and 'delegate' set if it wanted to delegate upgrade management to another server, or 'upgrade' and 'delegate' set if it wanted to delegate lease management.
The only mandatory field in the response is 'nonce', which prevents replay attacks. If the 'lease' field is absent, then the server does not have a newer activation lease to give to the client. If the 'delegate' field is absent, then the response of this server is authoritative. If the 'upgrade' field is absent, the server judges the client's software version adequate for the time being. The options are not exclusive -- for example, the response might have both 'lease' and 'delegate' set if it wanted to delegate upgrade management to another server, or 'upgrade' and 'delegate' set if it wanted to delegate lease management.

It is recommended that any server which returns some entries with the 'stolen' field return *all* entries with the 'stolen' field, to prevent network filtering of messages with 'stolen' set. The fixed size hash used as the payload is intended to prevent filtering from being able to distinguish between normal responses and responses indicating a stolen laptop. Care should be taken to ensure that these cases can not be easily distinguished by the presence or contents of other fields in the message. For a stateless upgrade server, the 'stolen' field can be safely omitted.


==OATC/Rainbow protocol==
==OATC/Rainbow protocol==

Revision as of 21:51, 19 September 2007


Pencil.png NOTE: The contents of this page are not set in stone, and are subject to change!

This page is a draft in active flux ...
Please leave suggestions on the talk page.

Pencil.png

This is a basic antitheft client/server protocol for FRS. It is expected that this protocol is temporary to a degree: we expect to have a more featureful management system at some point in the future. The primary goal of this protocol is to deploy something "good enough for now" that will allow us to upgrade to a revised featureful protocol at a later date, with the benefit of some experience with the upgrade system. At various points in the discussion below, we will flag features which are expected to be deprecated, replaced, or fleshed out later.

Antitheft client request

The antitheft client (OATC) will send periodically send requests to the canonical antitheft server. It is recommended that OATC send a request if (antitheft lease expiration time + time of last request) / 2 is earlier than the current time. This guarantees an server outage must last longer than (lease time / 2) in order to effect clients.

The client requests and responses are standard HTTP/1.1 in order to allow them to pass unmolested through the greatest varienty of (stateful) firewalls, NATs, and proxies.

The client request is:

POST /antitheft/1 HTTP/1.1
Host: antitheft.laptop.org
Authorization: OLPC-hashcash <hashcash>
Content-Type: application/x-www-form-urlencoded  

<form contents>

As should be obvious from the request, it is made to the URL http://antitheft.laptop.org/antitheft/1. The number at the end of the URL is a version string; later versions of this protocol will use a different suffix. The 'Authorization' line is optional, but may trigger a 401 response if omitted. The response will have the following form.

 HTTP/1.1 401 Hashcash required.
 WWW-Authenticate: <oatc-bits> <oatc-nonce>

The authorization line mitigates DoS attacks. The '<hashcash>' element should be a version 1 hashcash stamp with the resource string equal to <oatc-nonce> and the bits field greater than or equal to <oatc-bits>.

If required, the hashcash should be checked before the form contents are accepted. A limited-size buffer may be used for the first recv on the stream to enforce this, so extra headers (or re-ordered headers) should be avoided.

The form contents are encoded according to their content type. The fields are:

serialnum
the serial number of the laptop
version
the URI identifying the currently-running version on the laptop (or hash?)
stream
an opaque string identifying the "upgrade stream" to which the user has subscribed themself. Note that future upgrade servers may ignore this field in favor of central management
nonce
an opaque string randomly generated by the client so as to be highly likely unique
delegated
an optional hint -- see the delegation response for more information

Antitheft server response

The response status code should be 200 if the response is accepted or 401 if the hashcash authentication failed.

Response format:

HTTP/1.1 200 OK
Content-Type: text/x-json

<reponse body>

The reponse body is a Canonical JSON envelope with type 'oatc-signed-resp' and version 1. The body is a tuple:

(data, credential)

where the signature field is a credential on the data field, signed with the "antitheft server" key. This key validates this response as coming from a trusted antitheft server; it is not the same as the antitheft lease key, upgrade signing key, or kernel signing key.

The 'data' field in the 'oatc-signed-resp' object is another Canonical JSON envelope with type 'oatc-resp' and version 1. The body is a map with the following keys and data:

nonce
value nonce-data
the nonce-data must match the nonce provided in the request exactly.
stolen
hash
the stolen field, if present, contains a ascii hexadecimal-encoded sha256 hash. The hash is either of the string "<uuid>:<nonce>" or of "<uuid>:<nonce>:STOLEN".
upgrade
value (hash, priority, hint)
the hash identifies the new version to which we should upgrade
the priority is a string. if it has the contents "urgent" we should reboot immediately after receiving this upgrade, because it has critical security implications. Other contents are ignored.
the hint is a map from strings to strings. The keys identify various upgrade mechanisms, and the values give a hint as to where that upgrade mechanism can find the upgrade identified by the hash.
delegate
value (url, key_or_fingerprint)
the url identifies another antitheft server at which we should repeat our request.
if the 'delegated' field in the response was present, the key_or_fingerprint field will be a short opaque fingerprint corresponding to a key which the client is already expected to have.
if the 'delegated' field in the response was absent, the key_or_fingerprint field will be a key object identifying the public key with which the delegated server is expected to sign its responses.
public keys are large objects; the 'delegated' hint tries to avoid sending them when unnecessary. If the delegation key changes and the client finds that it doesn't in fact have a key matching the sent fingerprint, it must retry the request to the original server with the 'delegated' hint absent.
lease
value lease-data
the lease-data is an activation lease in the firmware activation lease format.

The only mandatory field in the response is 'nonce', which prevents replay attacks. If the 'lease' field is absent, then the server does not have a newer activation lease to give to the client. If the 'delegate' field is absent, then the response of this server is authoritative. If the 'upgrade' field is absent, the server judges the client's software version adequate for the time being. The options are not exclusive -- for example, the response might have both 'lease' and 'delegate' set if it wanted to delegate upgrade management to another server, or 'upgrade' and 'delegate' set if it wanted to delegate lease management.

It is recommended that any server which returns some entries with the 'stolen' field return *all* entries with the 'stolen' field, to prevent network filtering of messages with 'stolen' set. The fixed size hash used as the payload is intended to prevent filtering from being able to distinguish between normal responses and responses indicating a stolen laptop. Care should be taken to ensure that these cases can not be easily distinguished by the presence or contents of other fields in the message. For a stateless upgrade server, the 'stolen' field can be safely omitted.

OATC/Rainbow protocol

There are two files in /security which rainbow/userland uses to communicate with the antitheft client (oatc):

/security/update-stream
/security/update-version

The 'update-stream' file contains the string which is to be included in the 'stream' field of the antitheft request. The 'update-version' file contains the string which is to be included in the 'version' field of the antitheft request.

There is an additional unix datagram socket in

/security/events

which is used to communicate between rainbow and oatc. A datagram is sent from oatc to rainbow with the json-encoded 'oatc-resp' object whenever an antitheft response is received. A short timeout on the send prevents userland from hanging oatc. The contents are parsed and used to trigger upgrades.

Userland may also send blackbox data via this socket to oatc; this is left unspecified (and unimplemented) at the present.