Antitheft HowTo: Difference between revisions

From OLPC
Jump to navigation Jump to search
(Proper name for Open Firmware)
 
(13 intermediate revisions by 8 users not shown)
Line 2: Line 2:




=Example scenarios=
==Example scenarios==


==Upgrade and activate a set of XOs==
===Upgrade and activate a set of XOs===


To accomplish this, you need 3 machines in total.
To accomplish this, you need 3 machines in total.
Line 14: Line 14:
And your master keys.
And your master keys.


===Steps===
====Steps====


# On the MSS, create a lease.sig file with leases for all the XOs you will upgrade and activate.
# On the MSS, create a lease.sig file with leases for all the XOs you will upgrade and activate.
# On the XS, load the lease.sig file so that xs-activation can use it
# On the XS, load the lease.sig file so that xs-activation can use it
# On the NANDBlast machine, prepare to run nb-secure, as described in [[Multicast_NAND_FLASH_Update#NANDblasting_a_Signed_NAND_Image_File]]
# On the NANDBlast machine, prepare to run nb-secure, as described in [[Nandblaster_for_XO-1#NANDblasting_a_Signed_NAND_Image_File|NANDblasting a Signed NAND Image File]]
# Setup the XS and the NANDBlast machine in the "upgrade" room and commence the unpack/start process
# Setup the XS and the NANDBlast machine in the "upgrade" room and commence the unpack/start process


=Procedures=
==Procedures==


==Prepare an XO as the Master Signing Server (MSS)==
===Prepare an XO as the Master Signing Server (MSS)===


::''This machine is only used to generate leases, devkeys or delegations. In other words, it is of occassional use, and should be kept in a secure place at all times.''
::''This machine is only used to generate leases, devkeys or delegations. In other words, it is of occassional use, and should be kept in a secure place at all times.''
Line 32: Line 32:
## Install it with <code>rpm -ivh olpc-bios-crypto-(version).rpm</code>
## Install it with <code>rpm -ivh olpc-bios-crypto-(version).rpm</code>
# Make a new directory to store the master keys: <code>mkdir /root/masterkeys</code>
# Make a new directory to store the master keys: <code>mkdir /root/masterkeys</code>
# Copy the master keys into <code>/root/masterkeys</code> - you will normally have the files <code>developer.private developer.public fs.private fs.public fw.private fw.public lease.private lease.public oats.private oats.public os.private os.public</code>
# If you have the master keys, copy them into <code>/root/masterkeys</code> - you will normally have the files <code>developer.private developer.public fs.private fs.public fw.private fw.public lease.private lease.public oats.private oats.public os.private os.public</code>


Done! Now keep this machine in a safe location.
Done! Now keep this machine in a safe location, and do _not_ connect it to any network.


==Generate activation leases on the MSS==
===Create your master keys on the MSS===


You first need to prepare your Master Signing Server. Logged in to the MSS, you want to create all the required keys:
You will usually have a spreadsheet provided by OLPC with the serial numbers, uuids and box number. You need to define which XOs / boxes activated...


cd /root/masterkeys
=== Stage 1 - create the CSV file ===
obc-makekey os
obc-makekey developer
obc-makekey fs
obc-makekey fw
obc-makekey lease
obc-makekey oats

this will generate 2 files for each key; the private key, and the public key. The directory will now hold these 12 files:

developer.private
developer.public
fs.private
fs.public
fw.private
fw.public
lease.private
lease.public
oats.private
oats.public
os.private
os.public

Zip up all the keys, copy them to various storage mediums (USB keys, CD-ROMs) and store them in different safe locations. '''Do not email them or store them on computers that are connected to any network'''.

zip allkeys.zip *.public *.private

Zip up the public keys, you will need to send them to the OLPC team to include them on the manufacturing process, and possibly for a keyjector for your existing XOs.

zip publickeys.zip *.public

===Test the new keys===

To test the keys on an XO we will need to

* Get an XO that is unlocked / devkeyed.
* Install the new keys as additional keys.
* Sign an OS image, its kernel and firmware with the new keys -- install the OS image.
* Generate leases and devkeys from the new keys, and use them to activate and unlock the machine.

====Install the new keys====

The filenames are too long for a FAT USB disk, so

mkdir /root/pubkeys.short
cp /root/master/*.public /root/pubkeys.short
cd /root/pubkeys.short
rename .public .pub *.public
mv developer.pub dev.pub

Now copy them to a USB disk:

cp *.pub /media/mydisk/
umount /media/mydisk/

To install the new keys -- boot on an unlocked XO, hold the Escape key to get to the Open Firmware prompt, and then:

ok add-tag-from-file d1 u:\dev.pub
ok add-tag-from-file w1 u:\fw.pub
ok add-tag-from-file s1 u:\fs.pub
ok add-tag-from-file o1 u:\os.pub
ok add-tag-from-file a1 u:\lease.pub
ok add-tag-from-file t1 u:\oats.pub

===Generate activation leases on the MSS===

You will usually have a spreadsheet provided by OLPC with the serial numbers, uuids and box number. You need to select those XOs you will be generating activations for

==== Stage 1 - create the CSV file ====


# open spreadsheet in OpenOffice Calc
# open spreadsheet in OpenOffice Calc
Line 64: Line 132:
SCH9950296C,377F6B80-DDA9-4A89-9C73-8C500C79AA8A
SCH9950296C,377F6B80-DDA9-4A89-9C73-8C500C79AA8A


=== Stage 2 - generating lease.sig ===
==== Stage 2 - generating lease.sig ====


'''Preparations''': Copy the generated CSV file to a USB stick.
'''Preparations''': Copy the generated CSV file to a USB stick.
Line 75: Line 143:
Things are in place now. Decide the number of days of validity for the leases (we'll use 10 in this example). The command to generate the leases will be (in one line):
Things are in place now. Decide the number of days of validity for the leases (we'll use 10 in this example). The command to generate the leases will be (in one line):


obc-make-lease-from-csv --signingkey /root/masterkeys/lease /root/laptops/schoolname/schoolname.csv 10 | obc-format_as_cjson_leases > /root/laptops/schoolname/lease.sig
obc-make-lease-from-csv --signingkey /root/masterkeys/lease /root/laptops/schoolname/schoolname.csv 10 | \
obc-format_as_cjson_leases > /root/laptops/schoolname/lease.sig


Now you have a lease.sig file in the /root/laptops/schoolname/ directory. To use it...
Now you have a lease.sig file in the /root/laptops/schoolname/ directory. To use it...
Line 82: Line 151:
* To use it in an XS, you will want to see the instructions that follow (in the "Load a lease.sig file on an XS")
* To use it in an XS, you will want to see the instructions that follow (in the "Load a lease.sig file on an XS")


== Loading activation-related files on an XS ==
=== Loading activation-related files on an XS ===


This technique is to load any <code>lease.sig d-lease.sig d-oats.sig server.pri server.pub</code> files into an XS.
This technique is to load any <code>lease.sig d-lease.sig d-oats.sig server.pri server.pub</code> files into an XS.
Line 88: Line 157:
For more details, see [[XS-activation]]
For more details, see [[XS-activation]]


=== If you are dealing with a single XS ===
==== If you are dealing with a single XS ====


For example, you have a lease.sig file containing leases for a number of XOs, and you want to load it on an XS.
For example, you have a lease.sig file containing leases for a number of XOs, and you want to load it on an XS.
Line 107: Line 176:
M=`sha1sum d-oats.sig d-lease.sig server.pri server.pub` && echo "$M" > manifest.sha1
M=`sha1sum d-oats.sig d-lease.sig server.pri server.pub` && echo "$M" > manifest.sha1


=== If your are dealing with many XSs ===
==== If your are dealing with many XSs ====


The process is the same as for one server, but must be made ''in a subdirectory with a name that matches the name given to the server''. For example for a server where <code>hostname -f</code> returns <code>schoolserver.'''fidelcoloma'''.fundacion.org.ni</code>, we do:
The process is the same as for one server, but must be made ''in a subdirectory with a name that matches the name given to the server''. For example for a server where <code>hostname -f</code> returns <code>schoolserver.'''fidelcoloma'''.fundacion.org.ni</code>, we do:
Line 125: Line 194:
This allows the preparation of a single USB stick with different files for each School Server.
This allows the preparation of a single USB stick with different files for each School Server.


=== Following the process ===
==== Following the process ====


This is only for debugging the process if you find problems.
This is only for debugging the process if you find problems.
Line 134: Line 203:


When you insert the USB stick messages will appear there as the XS reads the contents. This same log shows the activity of the lease server.
When you insert the USB stick messages will appear there as the XS reads the contents. This same log shows the activity of the lease server.

=Discussion=

== RTC sync ==

With OS 8.2.2 and newer, the laptop can -- in some cases -- sync its RTC (Real Time Clock) to a signed timestamp sent by the server.

For this to work with the local XS, the pre-requisites are...

* XO OS 8.2.2 or newer
* XS 0.6 or newer
* The XS must be running with delegated keys -- that is, have its own local OATS key and a delegation from the master OATS key to its local OATS key ''for the laptop involved''. This is specially important for the ''port 191'' part of the OATS protocol.
** In the future, this may be simplified for XSs that have reliable internet connectivity by using a proxy OATS server that forwards all requests to a central server for easier administration.

There are 2 situations where this can happen: during initramfs execution and during olpc-update-query.

'''Initramfs''': If the initramfs requests a new lease via the wireless network (usually because there is no lease, or the lease is expired), it will also request a signed time. If the server responds with a valid signed timestamp, the RTC is sync'ed to it. This uses the ''port 191'' part of the OATS protocol.

The initramfs implementation can help deal with laptops with marginal RTC batteries.

'''olpc-update-query''': when olpc-update-query hits the server (initially the local XS, then if possible the country-wide antitheft server), the response will contain a signed timestamp. If the difference between the signed timestamp and the RTC is more than 24hs, olpc-update-query will sync the RTC. If the difference is smaller, it will let ntpd handle the correction.

[[Category:SchoolServer]]

[[Category:Security]]

Latest revision as of 23:34, 6 October 2012

This document outlines antitheft-related procedures. Please discuss edits on server-devel@lists.laptop.org .


Example scenarios

Upgrade and activate a set of XOs

To accomplish this, you need 3 machines in total.

  • An XO acting as the Master Lease Signing Server (MSS)
  • An XS (can be XS-on-XO machine)
  • An XO running as NANDBlast sender

And your master keys.

Steps

  1. On the MSS, create a lease.sig file with leases for all the XOs you will upgrade and activate.
  2. On the XS, load the lease.sig file so that xs-activation can use it
  3. On the NANDBlast machine, prepare to run nb-secure, as described in NANDblasting a Signed NAND Image File
  4. Setup the XS and the NANDBlast machine in the "upgrade" room and commence the unpack/start process

Procedures

Prepare an XO as the Master Signing Server (MSS)

This machine is only used to generate leases, devkeys or delegations. In other words, it is of occassional use, and should be kept in a secure place at all times.
  1. Grab an XO, with the standard OS image. These notes are based on XO OS 8.2.1, but should work on future versions.
  2. Install the latest olpc-bios-crypto package:
    1. Download the latest one from [1]
    2. Install it with rpm -ivh olpc-bios-crypto-(version).rpm
  3. Make a new directory to store the master keys: mkdir /root/masterkeys
  4. If you have the master keys, copy them into /root/masterkeys - you will normally have the files developer.private developer.public fs.private fs.public fw.private fw.public lease.private lease.public oats.private oats.public os.private os.public

Done! Now keep this machine in a safe location, and do _not_ connect it to any network.

Create your master keys on the MSS

You first need to prepare your Master Signing Server. Logged in to the MSS, you want to create all the required keys:

 cd /root/masterkeys
 obc-makekey os
 obc-makekey developer
 obc-makekey fs
 obc-makekey fw
 obc-makekey lease
 obc-makekey oats

this will generate 2 files for each key; the private key, and the public key. The directory will now hold these 12 files:

 developer.private
 developer.public
 fs.private
 fs.public
 fw.private
 fw.public
 lease.private
 lease.public
 oats.private
 oats.public
 os.private
 os.public

Zip up all the keys, copy them to various storage mediums (USB keys, CD-ROMs) and store them in different safe locations. Do not email them or store them on computers that are connected to any network.

 zip allkeys.zip *.public *.private

Zip up the public keys, you will need to send them to the OLPC team to include them on the manufacturing process, and possibly for a keyjector for your existing XOs.

 zip publickeys.zip *.public

Test the new keys

To test the keys on an XO we will need to

  • Get an XO that is unlocked / devkeyed.
  • Install the new keys as additional keys.
  • Sign an OS image, its kernel and firmware with the new keys -- install the OS image.
  • Generate leases and devkeys from the new keys, and use them to activate and unlock the machine.

Install the new keys

The filenames are too long for a FAT USB disk, so

   mkdir /root/pubkeys.short
   cp /root/master/*.public /root/pubkeys.short
   cd /root/pubkeys.short
   rename .public .pub *.public
   mv developer.pub dev.pub

Now copy them to a USB disk:

   cp *.pub /media/mydisk/
   umount /media/mydisk/

To install the new keys -- boot on an unlocked XO, hold the Escape key to get to the Open Firmware prompt, and then:

   ok add-tag-from-file d1 u:\dev.pub
   ok add-tag-from-file w1 u:\fw.pub
   ok add-tag-from-file s1 u:\fs.pub
   ok add-tag-from-file o1 u:\os.pub
   ok add-tag-from-file a1 u:\lease.pub
   ok add-tag-from-file t1 u:\oats.pub

Generate activation leases on the MSS

You will usually have a spreadsheet provided by OLPC with the serial numbers, uuids and box number. You need to select those XOs you will be generating activations for

Stage 1 - create the CSV file

  1. open spreadsheet in OpenOffice Calc
  2. find them relevant XOs in the spreadsheet
  3. make a new page in the existing spreadsheet - give that page the

name of the school

  1. copy/paste the SN/UUID region to the new page, remove the "extra"

columns we don't need. Also make sure you don't include the 'column headers' row.

  1. Save the document
  2. Make sure you are on the spreadsheet page for the right school
  3. Now use the "File->Save As..." menu option to create a new file.

The file format must be CSV. The file name must be the name of the school.

  1. OpenOffice will offer a "Text export / field options" dialogue...
    1. Character set: leave it as it is (Unicode UTF-8).
    2. Field separator: leave it as it is(comma).
    3. Text separator: Delete it, so that the option is empty.
  2. OpenOffice will warn you that it is only exporting the 'current page'. Perfect, that's exactly what we want'

Now you should have a CSV file that is just serial numbers and uuids. The command head myfile.csv should give you five lines, each looking like:

SCH9950296C,377F6B80-DDA9-4A89-9C73-8C500C79AA8A

Stage 2 - generating lease.sig

Preparations: Copy the generated CSV file to a USB stick.

On the MSS

  1. If it doesn't exist, make a "/root/laptops/" directory: mkdir /root/laptops
  2. Make a directory for the files related to this school: mkdir /root/laptops/schoolname
  3. Plug the USB stick into the machine, it will be mounted under the /media directory. Copy the CSV file to your /root/laptops/schoolname directory.

Things are in place now. Decide the number of days of validity for the leases (we'll use 10 in this example). The command to generate the leases will be (in one line):

obc-make-lease-from-csv --signingkey /root/masterkeys/lease /root/laptops/schoolname/schoolname.csv 10 | \
   obc-format_as_cjson_leases > /root/laptops/schoolname/lease.sig

Now you have a lease.sig file in the /root/laptops/schoolname/ directory. To use it...

  • To use it directly on XOs, copy it to the top directory of a USB stick.
  • To use it in an XS, you will want to see the instructions that follow (in the "Load a lease.sig file on an XS")

Loading activation-related files on an XS

This technique is to load any lease.sig d-lease.sig d-oats.sig server.pri server.pub files into an XS.

For more details, see XS-activation

If you are dealing with a single XS

For example, you have a lease.sig file containing leases for a number of XOs, and you want to load it on an XS.

 # On a USB stick, make an 'xs-activation' directory
 mkdir /media/MYDISK/xs-activation
 # Copy the lease.sig file in there...
 cp /path/to/lease.sig /media/MYDISK/xs-activation/
 # Change to the directory
 cd /media/MYDISK/xs-activation/
 # Generate the manifest 
 M=`sha1sum lease.sig` && echo "$M" > manifest.sha1
 # Check that the manifest is OK
 sha1sum -c manifest.sha1

If you have several files, list them all when generating the manifest, like this:

 M=`sha1sum d-oats.sig d-lease.sig server.pri server.pub` && echo "$M" > manifest.sha1

If your are dealing with many XSs

The process is the same as for one server, but must be made in a subdirectory with a name that matches the name given to the server. For example for a server where hostname -f returns schoolserver.fidelcoloma.fundacion.org.ni, we do:

 # On a USB stick, make an 'xs-activation' directory
 mkdir /media/MYDISK/xs-activation
 mkdir /media/MYDISK/xs-activation/fidelcoloma
 # Copy the lease.sig file in there...
 cp /path/to/lease.sig /media/MYDISK/xs-activation/fidelcoloma
 # Change to the directory
 cd /media/MYDISK/xs-activation/fidelcoloma
 # Generate the manifest 
 M=`sha1sum lease.sig` && echo "$M" > manifest.sha1
 # Check that the manifest is OK
 sha1sum -c manifest.sha1

This allows the preparation of a single USB stick with different files for each School Server.

Following the process

This is only for debugging the process if you find problems.

Before you insert the USB stick into the XS, login and run

tail -f /var/log/user.log

When you insert the USB stick messages will appear there as the XS reads the contents. This same log shows the activity of the lease server.

Discussion

RTC sync

With OS 8.2.2 and newer, the laptop can -- in some cases -- sync its RTC (Real Time Clock) to a signed timestamp sent by the server.

For this to work with the local XS, the pre-requisites are...

  • XO OS 8.2.2 or newer
  • XS 0.6 or newer
  • The XS must be running with delegated keys -- that is, have its own local OATS key and a delegation from the master OATS key to its local OATS key for the laptop involved. This is specially important for the port 191 part of the OATS protocol.
    • In the future, this may be simplified for XSs that have reliable internet connectivity by using a proxy OATS server that forwards all requests to a central server for easier administration.

There are 2 situations where this can happen: during initramfs execution and during olpc-update-query.

Initramfs: If the initramfs requests a new lease via the wireless network (usually because there is no lease, or the lease is expired), it will also request a signed time. If the server responds with a valid signed timestamp, the RTC is sync'ed to it. This uses the port 191 part of the OATS protocol.

The initramfs implementation can help deal with laptops with marginal RTC batteries.

olpc-update-query: when olpc-update-query hits the server (initially the local XS, then if possible the country-wide antitheft server), the response will contain a signed timestamp. If the difference between the signed timestamp and the RTC is more than 24hs, olpc-update-query will sync the RTC. If the difference is smaller, it will let ntpd handle the correction.