Activation and developer keys: Difference between revisions

From OLPC
Jump to navigation Jump to search
No edit summary
(..)
Line 33: Line 33:
#* In all builds, you can type '''file:///home/.devkey.html''' in the browse location field to get to the request page.
#* In all builds, you can type '''file:///home/.devkey.html''' in the browse location field to get to the request page.
#* In recent builds, "Get a developer key" is at the bottom of the Browse start page.
#* In recent builds, "Get a developer key" is at the bottom of the Browse start page.
#* In older builds (8.1, 703 and higher), click "activities" in the OLPC Library left-hand navigation, click on the sub-menu "find activities", and at the bottom of the page that displays is the "apply for developer key" link.
#* In older builds (8.1, 703 and higher), click "activities" in the OLPC Library left-hand navigation, click on the sub-menu "find activities", and at the bottom of the page that displays is the "apply for developer key" link. Also, under "books" in the OLPC Library, click on the sub-menu "explore your xo", click "troubleshooting", and under "How do I get a developer key for my laptop" is a link to "submit this form"
#* In older builds (8.1, 703 and higher), you can also click "books" in the OLPC Library left-hand navigation, click on the sub-menu "explore your xo", click "troubleshooting", and under "How do I get a developer key for my laptop" is a link to "submit this form"
#* In still older builds (7.1, 650, 653, and 656), click on the Library link "other" and then on "about your xo". Click on the "apply for a developer key" link at the very bottom of the page. (You can press the 'check mark' (✓) game key to quickly get to the bottom of the page.)
#* In still older builds (7.1, 650, 653, and 656), click on the Library link "other" and then on "about your xo". Click on the "apply for a developer key" link at the very bottom of the page. (You can press the 'check mark' (✓) game key to quickly get to the bottom of the page.)
# Follow the directions to apply for a developer key.
# Follow the directions to apply for a developer key; it should be created in a day or two.
# Go back to the request page when your key is ready, and follow the instructions to download your key to your XO.
# The key should be created in a day or two.
# Go back to the request page when your key is ready, and follow the instructions to download your key to your XO. Once your key has been created, you can return to this page at any time ''on your XO'' to re-download it; there will be no further creation delay.
#* Once your key has been created, you can return to this page at any time ''on your XO'' to re-download it; there will be no further creation delay.
# [[Reboot]] your XO.
# [[Reboot]] your XO.

# Please make a copy of your developer key on some other computer, one that gets backed up regularly, in case this one is lost. You may want to copy your developer key from /security/develop.sig on the build in NAND flash to /security/develop.sig on a USB key or SD card, in case you need it later.
However you get a key, please make a copy of it on some other computer, one that gets backed up regularly, in case this one is lost. You may want to copy your developer key from /security/develop.sig on the build in NAND flash to /security/develop.sig on a USB key or SD card, in case you need it later.


''Tip:'' if the typeface is too difficult to read easily, you can use Browse's Zoom options (in the View menu) to make it larger. Alternatively, you can copy the text and paste it into the Write activity, where you can resize it.
''Tip:'' if the typeface is too difficult to read easily, you can use Browse's Zoom options (in the View menu) to make it larger. Alternatively, you can copy the text and paste it into the Write activity, where you can resize it.


==Getting a developer key without WiFi==
==Getting a developer key without WiFi==
If you have some network access, you can:
You can do any of the following:
* use a [[USB ethernet adaptors|USB-to-wired ethernet adapter]] to get your XO on the net, then follow the above instructions.
* use a [[USB ethernet adaptors|USB-to-wired ethernet adapter]] to get your XO on the net, then follow the above instructions.
* you can copy the file /home/.devkey.html from the XO to another (network-connected) machine, and perform the process from that machine. Entering the following command in the [[Terminal]] activity will copy it to any USB devices connected:
* copy the file /home/.devkey.html from the XO to another (network-connected) machine, and perform the process from that machine. Entering the following command in the [[Terminal]] activity will copy it to any USB devices connected:
** <tt>cp -p /home/.devkey.html /media/*/devkey.html</tt>
** <tt>cp -p /home/.devkey.html /media/*/devkey.html</tt>

* You can submit a written request via snail mail.<br/>The contact address on the OLPC website should work:<br/>One Laptop per Child<br/>P.O. Box 425087<br/>Cambridge, MA 02142
*Follow the instructions below:


== Getting a developer key without network ==
== Getting a developer key without network ==

=== via snail mail ===
You can submit a written request via snail mail to:
: One Laptop per Child<br/>P.O. Box 425087
: Cambridge, MA 02142

Your key will be mailed back to you.



=== If the machine won't boot ===
=== If the machine won't boot ===
==== Revert to a previous OS image ====
First, try booting with the 'O' (circle) gamepad key held down. That will attempt to boot a previous version of the OS; if your problem was that you attempted to update to an unsigned kernel without a developer key, this will get you running again, and you can use the easier developer key mechanisms above.
First, try booting with the 'O' (circle) gamepad key held down. That will attempt to boot a previous version of the OS, after which you can use one of the options above.


==== Generate a laptops.dat file ====
Otherwise, you need to go the slow way. It requires a USB memory stick, and manual assistance from someone at OLPC. To start the process, you will need to provide OLPC with both the Serial Number of your machine, and its UUID. The Serial Number is conveniently printed on a sticker in the battery compartment, and looks like "CSN74701E2F". The UUID is unfortunately only stored internally. To get it, you'll have to download a pair of signed Forth "Collector scripts" onto a USB memory stick (see below), plug it into your laptop, power it on, let it do its thing, and then remove the USB stick and use a different computer to send the resulting <tt>laptops.dat</tt> file to OLPC. That process is described below. How the Serial Number and UUID in the laptops.dat file turns into a developer key is still a manual process. Until we improve the "back end" of this operation, please just send email to help@laptop.org that describes your problem, includes the serial number, and attaches the resulting <tt>laptops.dat</tt> file.
See [[#Collecting serial numbers with a USB stick|the USB stick method]] described below. You can collect a laptops.dat file with the UUID information of your machine, or of many machines, with a single stick.


=== Getting devkey data via USB stick ===
===Collecting serial numbers and UUID's for one or many XOs===
This requires a USB memory stick, and manual assistance from someone at OLPC. The memory stick must be set up to work as a ''collection stick'' by adding code that at boot time copies information from the XO to itself. After using it, you should send the resulting file to OLPC.


<!--To start the process, you will need to provide OLPC with both the Serial Number of your machine, and its UUID. The Serial Number is conveniently printed on a sticker in the battery compartment, and looks like "CSN74701E2F". The UUID is unfortunately only stored internally.
First, you must set up a "Collection stick".
To get it, you'll have to -->
This is a USB flash drive with special code that at boot time copies information from the XO to itself.


* Set up a collection stick
* Plug the stick it into your laptop and power it on
* It will display a pretty "XO" screen and then a short message like "SHFxxxxxxxx nnnnnnnnnnnnnnn; Laptop data recorded successfully". After a few seconds it will power itself off or indicate it is done.
* Remove the USB stick and move the file to a different computer
* Email the <tt>laptops.dat</tt> file to help@laptop.org . Please describe your problem, including the serial number (printed inside your battery compartment, visible when you remove the battery), and attach the resulting <tt>laptops.dat</tt> file.

==== Setting up a collection stick ====
# Download [[media:Actos.zip|Actos.zip]] and [[media:Runos.zip|Runos.zip]] (its source code in Forth, if you're interested, is at http://dev.laptop.org/git?p=users/cscott/actkey; it will only run if it's put into a signed zip file.)
# Download [[media:Actos.zip|Actos.zip]] and [[media:Runos.zip|Runos.zip]] (its source code in Forth, if you're interested, is at http://dev.laptop.org/git?p=users/cscott/actkey; it will only run if it's put into a signed zip file.)
#*Actos.zip and Runos.zip are identical, but secure boot will use one or the other depending on your laptop's activation status, which we may not know. So include both.
#*Actos.zip and Runos.zip are identical, but secure boot will use one or the other depending on your laptop's activation status, which we may not know. So include both.
Line 69: Line 86:
#* Most USB flash drives use FAT or FAT32 when you buy them (except "U2" memory sticks which probably won't work; they contain ugly DRM stuff).
#* Most USB flash drives use FAT or FAT32 when you buy them (except "U2" memory sticks which probably won't work; they contain ugly DRM stuff).
# Your USB flash drive should contain these files (and nothing else in the boot directory):
# Your USB flash drive should contain these files (and nothing else in the boot directory):
#*boot/
#:boot/
#*boot/Actos.zip
#:boot/Actos.zip
#*boot/Runos.zip
#:boot/Runos.zip
# If there is an old <tt>laptops.dat</tt> file on the USB flash drive from an earlier collection of laptops, delete it.
# If there is an old <tt>laptops.dat</tt> file on the USB flash drive from an earlier collection of laptops, delete it. The USB flash drive can have any other files on it that you like.
#* The USB flash drive can have any other files on it that you like.


Now, for each laptop that you want to get a Developer Key for (maybe only one):


==== Getting devkey data for many XOs at once ====
# Insert your "Collection stick" in one of the USB ports on the XO.
For each laptop that you want to get a Developer Key for:
# Power on the XO with the power key.
#* This will put your Serial Number and UUID into the <tt>laptops.dat</tt> file on your "Collection stick" (it creates the file if it needs to).
# It will display a pretty "XO" screen and then a short message like "SHFxxxxxxxx nnnnnnnnnnnnnnn; Laptop data recorded successfully". After a few seconds it will power itself off.
# When the machine powers itself off, remove your "Collection stick".


# Repeat the above process, inserting your collection stick and powering on the laptop, for each XO in turn.
Repeat the above with each laptop that you want to create keys for (in most cases, only one laptop). The "Collection stick" will append the information for each new laptop to the <tt>laptops.dat</tt> file, so do not delete the <tt>laptops.dat</tt> file in between.
#* This will combine metadata for each laptop into one laptops.dat file, so do not delete the <tt>laptops.dat</tt> file in between.

# Email the resulting file to help@laptop.org, indicating the # of laptops you need keys for.
When you're done, plug your "Collection stick" into another computer, and send the collected information to OLPC.
If you haven't been instructed any other way to send it, put it in an email to help@laptop.org, tell us that you need a developer key for laptop(s) that won't boot, and insert or attach the <tt>laptops.dat</tt> file into the email message. If you have already interacted with help@laptop.org about this laptop, just reply to their last message to you, so your laptops.dat file will go into the same trouble ticket as the rest of your trouble report.


Then wait for OLPC to send you your Developer key(s) and/or Activation key(s).
Then wait for OLPC to send you your Developer key(s) and/or Activation key(s).



=== What to do when you receive your activation or developer keys ===
=== What to do when you receive your activation or developer keys ===

Revision as of 23:02, 25 September 2008

Translate this page with Google -español -български -中文(中国大陆) -中文(臺灣) -hrvatski -čeština -dansk -Nederlands -suomi -français -Deutsch -Ελληνικά -हिन्दी -italiano -日本語 -한국어 -norsk -polski -português -română -русский -svenska


  This page is monitored by the OLPC team.
  english | español HowTo [ID# 168054]  +/-  


A developer key is a file containing cryptographic information tied to a specific XO laptop.

What you can do with a developer key

If the boot firmware sees a developer key, it makes the XO laptop work just like any ordinary PC-style laptop, in the sense that it will let you interrupt the boot process and enter commands; and it will try to boot and run any program you supply to it, no matter whether the OLPC organization has tested or signed it. The laptop also works this way if its firmware security is disabled. OLPC produces many unsigned "development builds" of the operating system, which will only work in your laptop if you have a developer key. Also, if your laptop refuses to boot because the clock is set wrong, or complains about an unsigned kernel, getting a developer key is a critical part of diagnosing and/or fixing the trouble.

If you don't have a developer key, and the laptop has firmware security enabled, it will not let you do anything except boot the operating system and use the provided software. If you insert a USB memory stick or SD card, the boot firmware will only boot from it if the files are tested and cryptographically signed by OLPC.

Some laptops sent to schools in developing countries have firmware security enabled, depending on the wishes of that country's education system. Laptops that were sent to Give One, Get One donors also have firmware security enabled.

  1. The firmware will look for a developer key on your laptop's internal flash memory; on any USB memory stick that's plugged in; and on any SD card that's plugged in. It needs to be in /security (See Firmware Security for the gory details.)
  2. With a developer key, whenever the laptop boots, the firmware will give you the option to hit Escape (the upper left key, marked with an X in a circle) and get an ok prompt, which lets you enter commands in Forth. If you don't press Escape, after a short countdown the firmware continues booting the operating system.
    • This is the insecure boot process, and it will boot into any image you install on the xo.
    • Rather than drawing pretty pictures on the screen, lots of text messages will be displayed, and will eventually scroll up the screen. This is normal, and can be useful for diagnosing problems in your laptop.
    • The insecure boot process does not automatically upgrade firmware; you will be responsible for updating your firmware yourself.

Disabling security

One of the commands you can enter will enable this situation permanently, even without a developer key. This process is reversible.

  1. If you type 'disable-security' at the ok prompt, firmware security will be turned off on your laptop permanently. (This isn't necessary, but in some cases useful; see below.)
    • If you ever do a fresh install of the operating system (a complete overwrite of the internal flash memory; i.e. not olpc-update), you will lose the developer key (stored in /security/develop.sig). If you haven't disabled security, and if the build you overwrote with isn't signed, your laptop won't boot by default. You can either reflash again with a signed image to recover, or insert a USB memory stick or SD card with your developer key on it (this is why you should always be sure to backup develop.sig).
    • Even if security is disabled, you can re-enable it for a single boot by pressing the X gamepad key while turning the power on. This is useful to do firmware upgrades from signed builds. It can also help to test secure boot on release candidates.
    • You can reverse the 'disable-security' command with 'enable-security' at the ok prompt.

Getting a developer key for your running XO laptop

  1. On your XO, open the Browse activity.
  2. There's a "Developer key request" web page on the XO to apply for a key. There are several ways to navigate to this page:
    • In all builds, you can type file:///home/.devkey.html in the browse location field to get to the request page.
    • In recent builds, "Get a developer key" is at the bottom of the Browse start page.
    • In older builds (8.1, 703 and higher), click "activities" in the OLPC Library left-hand navigation, click on the sub-menu "find activities", and at the bottom of the page that displays is the "apply for developer key" link. Also, under "books" in the OLPC Library, click on the sub-menu "explore your xo", click "troubleshooting", and under "How do I get a developer key for my laptop" is a link to "submit this form"
    • In still older builds (7.1, 650, 653, and 656), click on the Library link "other" and then on "about your xo". Click on the "apply for a developer key" link at the very bottom of the page. (You can press the 'check mark' (✓) game key to quickly get to the bottom of the page.)
  3. Follow the directions to apply for a developer key; it should be created in a day or two.
  4. Go back to the request page when your key is ready, and follow the instructions to download your key to your XO.
    • Once your key has been created, you can return to this page at any time on your XO to re-download it; there will be no further creation delay.
  5. Reboot your XO.

However you get a key, please make a copy of it on some other computer, one that gets backed up regularly, in case this one is lost. You may want to copy your developer key from /security/develop.sig on the build in NAND flash to /security/develop.sig on a USB key or SD card, in case you need it later.

Tip: if the typeface is too difficult to read easily, you can use Browse's Zoom options (in the View menu) to make it larger. Alternatively, you can copy the text and paste it into the Write activity, where you can resize it.

Getting a developer key without WiFi

If you have some network access, you can:

  • use a USB-to-wired ethernet adapter to get your XO on the net, then follow the above instructions.
  • copy the file /home/.devkey.html from the XO to another (network-connected) machine, and perform the process from that machine. Entering the following command in the Terminal activity will copy it to any USB devices connected:
    • cp -p /home/.devkey.html /media/*/devkey.html


Getting a developer key without network

via snail mail

You can submit a written request via snail mail to:

One Laptop per Child
P.O. Box 425087
Cambridge, MA 02142

Your key will be mailed back to you.


If the machine won't boot

Revert to a previous OS image

First, try booting with the 'O' (circle) gamepad key held down. That will attempt to boot a previous version of the OS, after which you can use one of the options above.

Generate a laptops.dat file

See the USB stick method described below. You can collect a laptops.dat file with the UUID information of your machine, or of many machines, with a single stick.

Getting devkey data via USB stick

This requires a USB memory stick, and manual assistance from someone at OLPC. The memory stick must be set up to work as a collection stick by adding code that at boot time copies information from the XO to itself. After using it, you should send the resulting file to OLPC.


  • Set up a collection stick
  • Plug the stick it into your laptop and power it on
  • It will display a pretty "XO" screen and then a short message like "SHFxxxxxxxx nnnnnnnnnnnnnnn; Laptop data recorded successfully". After a few seconds it will power itself off or indicate it is done.
  • Remove the USB stick and move the file to a different computer
  • Email the laptops.dat file to help@laptop.org . Please describe your problem, including the serial number (printed inside your battery compartment, visible when you remove the battery), and attach the resulting laptops.dat file.

Setting up a collection stick

  1. Download Actos.zip and Runos.zip (its source code in Forth, if you're interested, is at http://dev.laptop.org/git?p=users/cscott/actkey; it will only run if it's put into a signed zip file.)
    • Actos.zip and Runos.zip are identical, but secure boot will use one or the other depending on your laptop's activation status, which we may not know. So include both.
  2. Put these files in a directory called boot on a FAT-formatted or FAT32-formatted USB flash drive.
    • Most USB flash drives use FAT or FAT32 when you buy them (except "U2" memory sticks which probably won't work; they contain ugly DRM stuff).
  3. Your USB flash drive should contain these files (and nothing else in the boot directory):
    boot/
    boot/Actos.zip
    boot/Runos.zip
  4. If there is an old laptops.dat file on the USB flash drive from an earlier collection of laptops, delete it. The USB flash drive can have any other files on it that you like.


Getting devkey data for many XOs at once

For each laptop that you want to get a Developer Key for:

  1. Repeat the above process, inserting your collection stick and powering on the laptop, for each XO in turn.
    • This will combine metadata for each laptop into one laptops.dat file, so do not delete the laptops.dat file in between.
  2. Email the resulting file to help@laptop.org, indicating the # of laptops you need keys for.

Then wait for OLPC to send you your Developer key(s) and/or Activation key(s).


What to do when you receive your activation or developer keys

  1. You can use the same USB flash drive that you used as 'Collector stick', but rename the boot directory to something else (perhaps collboot), otherwise your laptop will just re-run the collection script.
  2. You'll receive one or two files from OLPC, probably by email. Extract the file or files using your email program.
  3. If you receive a lease.sig file, it's your activation key. (G1G1 laptops don't need one.) Copy the activation key (lease.sig) into the root directory of your USB flash drive.
  4. Make a directory called security in the root directory of your USB flash drive.
  5. Copy the developer key (develop.sig) into the security directory on the USB flash drive.
    • When you're done, these files will be there:
      • lease.sig (only if received)
      • security/
      • security/develop.sig
  6. OLPC may also send you other files to put on the USB flash drive, e.g. to help to patch or circumvent whatever problem is preventing your laptop from booting properly.
  7. With the laptop powered off, insert the USB flash drive in one of its USB ports.
  8. Power on the laptop.
  9. If the laptop wasn't previously activated... it will now boot properly
    • Any provided activation key will be copied to /security/lease.sig on the XO. You may want to keep the activation key around (or copy the activation key to your school server, if you have one) in case you ever need to wipe the XO and reflash it.
  10. If you're using the developer key, you should be able to get to the ok prompt, which you will see within the first few seconds of booting (along with a short countdown to give you time to hit the Escape key). This is your indication that the developer key has been found.
  11. The developer key is not automatically copied to your laptop's internal flash memory. You can do that once you have Linux running on it, by copying security/develop.sig from the USB flash drive into /security/develop.sig in the root filesystem of the laptop. You'll need to be root in a Terminal activity to do that; it can't be done from the Journal or the GUI.
  12. If the laptop is running Sugar, go into the Journal, position the mouse over the USB flash drive image at the bottom of the screen, wait until it pops up an "Unmount" button, then click on that. Wait until it has finished and doesn't show the USB flash drive image any more. Then it's safe to remove the USB flash drive from that laptop.
  13. If the laptop is at an "ok" prompt in the boot firmware, it's safe to remove the USB flash drive immediately.

If you submitted information for more than one laptop, you can then put the USB flash drive into the next laptop, and repeat the above process. The same USB flash drive, with the same lease.sig and develop.sig files, should work for all the laptops you included in the laptops.dat file.

See also

Note: the Developer key page generated by the OLPC Activation Service (in response to a developer key request from the XO) links to this page.