Activation and developer keys

From OLPC
Revision as of 07:07, 22 August 2013 by Quozl (talk | contribs) (remove duplicate collection stick information as it is now on another page)
Jump to navigation Jump to search
  This page is monitored by the OLPC team.
  english | español HowTo [ID# 291847]  +/-  
  • A developer key is a file named develop.sig containing cryptographic information tied to a specific XO laptop that can be used to disable various security features.
  • An activation key or activation is a file named lease.sig containing a cryptographic signature tied to a specific XO laptop and provides the ability for the system to run up until a set date and time.
  • The activation system is part of the security system. Therefore, when the security system is disabled (with a developer key), activations become irrelevant: they are not needed for system operation.
  • Laptops can have the security system active but also be preactivated meaning that they will never request or use an activation, even though the rest of the features of the security system remain active.

Is your laptop secured?

  • Give One, Get One 2007 and Give One, Get One 2008 customers received laptops with the security system fully enabled, but the laptops are also preactivated meaning that they do not require an activation. Developer keys are required for some operations.
  • If your laptop is part of a deployment, the choice of security, security + preactivation, or no security is defined by the deployment. When buying laptops from OLPC, the customer specifies their choice and the laptops are programmed accordingly at the factory (you may be able to determine this from the Manufacturing data page). In some cases, this choice is then changed manually by the customer after the laptops have been received.

What the security system does

  • Unless the laptop is preactivated, the system will only boot while it has a valid and non-expired activation.
  • The only operating systems images that can be installed are those that are signed by a trusted party (which can be OLPC, the deployment, etc, based on the laptop's configuration at the factory).
  • The only firmware releases that can be installed are those that are signed by a trusted party.
  • The only kernels and initramfs (boot code) that can be booted are those that are signed by a trusted party.
  • You cannot gain access to Open Firmware's ok prompt.

A developer key will disable all of these functions, providing no restrictions on what code can be ran and whether the laptop can or can't be used.

Where the developer key can be placed

When the XO boots, its firmware checks to see if security is enabled or permanently disabled (a system parameter). If it is enabled, it looks for the a developer key, at /security/develop.sig, on any USB flash drive or SD card that's plugged in, and on the internal disk storage. (See Firmware security for the gory details.)

If that file is there (and contains an appropriate string), the XO will act as though it is unsecured:

  • You will be able to interrupt the boot process and enter commands
  • You can run any program or disk image you supply to it, such as a Fedora or Debian Linux system.

Why you might want to unsecure your XO

OLPC and others produce unsigned operating system images for development and testing. These will only work on unsecured laptops.

Various repair procedures, such as reprogramming the clock require the security system to be disabled (perhaps only temporarily).

When "secured" laptops can be useful

This security is part of the Bitfrost security system, and is used to ensure that unless the user has specifically opted out, their basic operating software remains unmodified, and provides various antitheft controls. Many OLPC customers express that security and antitheft systems are of high priority.

How to tell if your laptop is secured

A fast way to tell is when the laptop is turned on after being off:

  • when secured, the firmware will not let you press the Escape key Esc.png to get an ok prompt, and will not boot from an unsigned USB drive.
  • when not secured, or with a developer key present, the firmware will let you press the Escape key to get an ok prompt, which lets you enter commands in Forth.
  • if you don't press the Escape key, the firmware continues booting the operating system.

A slow way to tell is once the laptop is booted, use the Terminal activity, and check the contents of the manufacturing data tags, using this command:

olpc-hwinfo mfg-tag wp && echo yes

It will say "yes" if the wp tag is present, which means security is enabled.

(olpc-hwinfo is a feature of recent operating system builds. If you see a command not found error, then read the manufacturing data tags manually by looking in /ofw/mfg-data or /proc/device-tree/mfg-data.)

Getting a developer key for your running XO laptop

There's a "Developer key request" web page on the XO to apply for a key.

  1. On your XO, open a new Browse activity, and navigate to the request page:
    • For release 8.2.0, 10.1.x, and later, click on the link "get a developer key" at the bottom of the Browse start page,
    • otherwise, type file:///home/.devkey.html in the browse location field and press enter.
  2. Follow the directions to apply for a developer key; it should be created in a day or two.
  3. 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.
  4. Reboot your XO.

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.

Using a developer key

Make back up copies!

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. Also, you should copy your developer key to /security/develop.sig on a USB drive, if you have one.

Disabling the security system

Once you have a developer key:

  • Make sure it is in the /security/ directory on your USB drive or SD card.
  • Plug it into your XO before booting it. Boot your XO with that drive/card plugged in.
  • You can now either immediately install unsigned software, or interact with the firmware -- including permanently disabling the firmware security system. (Once this is turned off, you will no longer need your XO's developer key to run the machine in "unsecured" mode.)

To permanently turn off firmware security:

  • Boot the XO as above, with a USB drive or SD card with the developer key plugged in. Interrupt the boot sequence: press the Esc.png Escape key a few times during the startup sound, just after turning the laptop on, to bring up the firmware Ok prompt. (for other ways to reach the prompt, see Ok prompt.)
  • Type disable-security. Press enter.
  1. If disable-security says "No wp tag", it means that security is already disabled.
  2. If disable-security says "Restarting to enable SPI flash writing. Try again after the system restarts.", you'll need to start over with the Esc key again as above.
  • When security is disabled, you can re-enable it for a single boot (say, to test how a secured machine would work) by pressing the X gamepad key while powering 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 by entering enable-security at the 'ok' prompt. Security will then be permanently enabled until disabled again.
  • You can see the raw manufacturing data where the disable-security setting is stored by typing ".mfg-data". See Manufacturing data for details.

Troubleshooting disabling of the security system

Some of us have had some issues with disabling the security when the developer key is on a USB drive. This may happen if the USB drive is incompatible with the firmware. If you experience this problem, try using an SD card instead. It should be vfat formatted.

If you are on Linux:

mkfs.vfat -I /dev/sdX

then mount the SD card

mount -t vfat /dev/sdX /media/yourmountpoint
cp develop.sig /media/yourmountpoint

Once you are done unmount your SD card:

umount /dev/sdX

then stick the SD into the XO (it is under the screen, you need to turn it -- it is on the right side), reboot and hold down Esc.png -- then you will get to an {ok} prompt type:

disable-security

it will automatically reboot to enable access to internal data, and you must repeat this step, then it will update the internal data and reboot again.

Once it finishes booting, copy the developer key to the disk:

cd /media/$some-automatically-mounted-name  
su
cp develop.sig /security

Now you can reboot and take out the SD card if you hit Esc.png it will bring you to the {ok} prompt


If you wipe out your developer key

If you reflash your XO you will remove /security/develop.sig. One way this can happen is if you ever do a fresh install of an operating system image using the clean-install procedure (rather than olpc-update). If you haven't disabled security and the OS image that overwrote flash is unsigned, then your laptop won't boot. But you have several options:

  • Revert to a previous OS image. Try pressing the 'O' (circle) gamepad key while booting. That will attempt to boot a previous version of the OS, and if it was signed it will succeed.
  • Reflash again with a signed OS image.
  • Insert a USB drive or SD card with your developer key on it in /security/develop.sig (this is why you should always be sure to backup develop.sig), which will allow booting of the unsigned OS image and/or let you get to the 'ok' prompt to disable security.

Once boot completes you can restore your developer key back to NAND flash by typing in a terminal something like

 cp -pi /media/MY_USB_NAME/security/develop.sig /security

or you can re-visit the "Developer key request" form and re-download your developer key. But you would be better off if you immediately disabled security, as described above; that never expires, unlike developer keys in NAND flash that often get overwritten.

Getting a developer key without WiFi

If you have wired network access, you can:

Getting a developer key without any network access

  • 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 /var/run/media/*/devkey.html

How to get a developer key when Browse freezes

At times Browse can freeze when trying to activate your key. An alternative way of activating is by starting Terminal or by pressing Ctrl+Alt+Friends key f2 small.png to get to a console and get the serial + uuid for activation. Once you see the terminal, you may need to type in "root" with no password to login.

Next type in:

vi /home/.devkey.html

on line 16, there should be the serial_num (write down what it says under VALUE="....") and what it says on line 17 the uuid VALUE=...". You will need this information to register for your key.

Next, on a computer that has web access and click on: https://activation.laptop.org/devkey/post/ and enter in the serial and uuid that you got from the .devkey.html file and click on "Request developer key".

You should then return to the web page after 24 hours. Your key will be ready for you.

Getting a developer key by postal mail

You can submit a written request via snail mail to one of OLPC's addresses listed on our Contact page.

You must include your serial number.

Your developer key will then be mailed back to you on paper. You will have to type it in to a develop.sig file. This is prone to error, so try hard to use other methods.

Getting a developer key without network

See collection stick for a method to get a developer key using a USB drive, for one laptop, or many.

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.