Welcome to xs-tools
====================

xs-tools contains a number of utilities for OLPC's School Server (XS),
and a means of installing and using gpg keys on the server.

The utilities are useful to prepare content for XS installs, and may
be useful in other contexts.  They use a simple library, gpgwrapper,
to performs simple authenticity checks on signed software.

When a usb drive is mounted, xs-tools will look to import new keys.

Tools
=====

xs-sum - A wrapper around sha1sum that checks whether a manifest is
         properly signed.

xs-check - Check that a single file is properly signed.

xs-encrypt - Encrypt a file using the public keys known to xs-tools.

Library
=======

gpgwrapper has two useful functions:

 check_sig(filename)                 -- make sure the file is signed.
 encrypt_file(plain_fn, cipher_fn)   -- encrypt a message.

See the module for further functions, classes and options (`pydoc
gpgwrapper`).  By default it uses the public keys in
/etc/pki/olpc/XS-trusted-keys, and it will only check for signatures
if /etc/xs-security-on exists.

/etc/xs-security-on
===================

This flag changes the behaviour of xs-sum and xs-check, and through
them, of other school server packages.  If it exists, xs-sum and
xs-check fail unless the content they handle is signed by known keys.
Without it, they carry on regardless.

The flag also affects the importation of keys via usb drives.

Importing keys
==============

When a USB drive is mounted, xs-tools will look for a directory called
'XS-trusted-keys' in the USB drive's root.  If it is there, it looks
in that directory for public keys to import.  Whether or not it does
import the keys depends on the presence of existing keys in
/etc/pki/olpc/XS-trusted-keys, on the presence of /etc/xs-security-on,
and on whether the existing keys sign the new ones.

If there are no public keys in /etc/pki/olpc/XS-trusted-keys, the new
keys will be imported regardless.  Otherwise, if /etc/xs-security-on
exists, each key for import needs to be signed by a known key; and if
it does not, no imports are possible.

NOTE: if an existing key has the same file name as an importable key,
it is replaced.

Key and signature format
========================

The public keys should be in ASCII armoured format, with a '.pub'
suffix, as would be created by this gpg command:

gpg --homedir $SOMEWHERE --export --armor --output $SOMEONE.pub

They should be signed in a detached format with the signature having
the additional suffix of '.sig', using a command along these lines:

gpg --armor --homedir $SIGNER_HOME -sb --output $SIGNEE.pub.sig $SIGNEE.pub

Other files to be verified by xs-check should be signed in the same
way (replacing $SIGNEE.pub with the filename).

Manifest format, and xs-sum usage
=================================

xs-sum checks a manifest against a directory's contents, and returns
an error unless it matches exactly.  If /etc/xs-security-on is set,
the manifest must be signed.

Neither the manifest nor its signature should be listed in the
manifest, so in case sha1sum catches up with itself, they are
typically created using a dance like this:

TMP=$(mktemp)
sha1sum * > $TMP
mv $TMP manifest.sha1
gpg --armor --homedir $SIGNER_HOME -sb --output manifest.sha1.sig manifest.sha1

Later the contents can be checked using:

TMPDIR=`mktemp -d`
mv manifest.sha1*  $TMPDIR/
xs-sum -c $TMPDIR/manifest.sha1

For more options, use xs-sum --help.

Files
=====

/etc/xs-security-on            -- touch this to enable checking
/etc/pki/olpc/XS-trusted-keys  -- trusted public keys stored here
/etc/xs-tools.conf             -- don't change this.

Where do these keys come from?
==============================

All the keys used by xs-tools are ASCII-armoured openPGP public keys.
Each has a corresponding private key that can be used to sign files
which can be verified by the public key, or to decrypt files that have
been encrypted with the public key.  The XS never uses private keys
directly.

If you do not have a gpg private key (or don't want to use it), you
can generate a new one with:

 gpg [--homedir $SOMEWHERE] --gen-key

gpg will ask you a series of questions.  The private key will be
stored in some way in the named directory (or ~/.gnupg by default) --
it doesn't matter how, because you always refer to it via the
directory.  The "keys and signature format" section, above, tells you
how to extract the public key.

Questions, discussion
---------------------

Mailing list: server-devel@lists.laptop.org

Source code:
  http://dev.laptop.org/git/users/martin/xs-tools.git  (browse)
  git://dev.laptop.org/users/martin/xs-tools.git       (clone)


Credits
-------

Martin Langhoff <martin@laptop.org>
Douglas Bagnall <douglas@paradise.net.nz>
