Developer keys: Difference between revisions

From OLPC
Jump to navigation Jump to search
m (Removing all content from page)
m (→‎Getting a developer key: Corrected fragment identifier.)
 
(10 intermediate revisions by 4 users not shown)
Line 1: Line 1:
{{draft}}

== What is a developer key? ==
A '''developer key''' is a file named '''develop.sig''' containing cryptographic information tied to a specific XO laptop that can be used by software to disable various security features.

See also [[Activation and developer keys]].

== Who uses developer keys? ==

Developer keys are requested and used by individual volunteers, developers, and testers. '''They are not intended to be used to customize XOs for large-scale OLPC deployments.''' Large-scale deployments work with OLPC to customize their build. See [[Developer key philosophy]] for the reasons why this feature was designed.

== What do developer keys do? ==

Developer keys allow you to:

* Install unsigned builds on your XO, such as builds from other deployments, or builds from active development, such as for build testing,
* Upgrade the firmware independently of the versions included with signed builds, such as for firmware testing,
* Work with the firmware, for diagnosis and repair, such as debricking,
* Defeat the activation lease mechanism,
* Gain full access on XOs that are bound to a deployment key.

== Getting a developer key ==

Since developer keys are generated for each individual laptop when they are requested, you must first have a specific XO in mind that you want to unlock. Once you have chosen the XO you want to unlock, there are several ways of getting a key for it, listed here in order of preference. After you get your developer key, proceed to the [[#Using a Developer Key|Using a Developer Key]] section below.

=== If your XO is connected to the internet ===

This is by far the easiest and fastest method. If you can connect your running XO to a wifi access point or use a [[USB ethernet adaptors|USB-to-wired ethernet adapter]] to get your XO online, please follow these instructions (the vast majority of developers use this method).

# On your XO, open the [[Browse]] activity and go to '''file:///home/.devkey.html'''. (In recent builds, "Get a developer key" is one of the links at the bottom of the Browse start page.)
# Follow the directions on that page to get a developer key.

Note that once your key has been created, you can return to this page in Browse at any time to re-download it.

=== If your XO is not connected to the internet ===

If your XO ''cannot'' be connected to the internet, but you have a USB storage device and access to a computer that ''is'' connected to the internet, you can copy the web page with the form to get a developer key to that computer:

# Copy the file <code>/home/.devkey.html</code> from your XO to the computer with internet access.
#* For example, entering the following command in the [[Terminal]] activity will copy the file you need to a USB device connected to your XO:<pre> cp -p /home/.devkey.html /var/run/media/*/devkey.html</pre>

# Open the <code>devkey.html</code> file in a browser on the computer with internet access and follow the directions on that page to get a developer key.

=== If you do not have internet access at all ===

This is very much '''not''' recommended, and extraordinarily rare, as most development work is done via email, chat, forums, and other internet-based communication mediums. However, if you ''must'' get a developer key and do not have access to the internet at all, you can submit a written request via snail mail to:

<pre>
One Laptop per Child
P.O. Box 425087
Cambridge, MA 02142
</pre>

Your key will be mailed back to you.

=== If your XO does not boot ===

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.

If that doesn't work, see the [[Collection key]] page and follow the procedures there. When sending your email, please describe your problem, including the serial number (printed inside your battery compartment, visible when you remove the battery) in addition to attaching the <tt>laptops.dat</tt> file. If OLPC has a fix for the problem that prevents your laptop from booting properly, we will also send you other files to put on the USB flash drive to help to patch or circumvent it.

=== Getting developer keys for many XOs at once ===

Follow the instructions on the [[Collection key]] page.

==Using a Developer Key==

''Note: This section and below needs a lot of work.''' [[User:Mchua|Mchua]]

=== 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 <tt>/security/develop.sig</tt> on a USB flash drive; then, if you have trouble booting an unsigned OS image, you can boot with the USB flash drive inserted without having to [[Clean-install_procedure|clean-install]].

=== What you can do ===

Once you have a developer key, you can choose to...
# By installing the developer key in /security/develop.sig, where it can be managed with the Security control panel (<trac>6428</trac>).
# By invoking 'disable-security' from the Open Firmware prompt to skip all key checking (until you invoke 'enable-security' again).

While this choice is left to the developer, the former option is recommended, because it exercises the key-checking and "pretty boot" code. This ensures that developers are regularly testing this code, so that any bugs can be quickly discovered and fixed--instead of making it to the machine of some poor six year old in Peru.

Using the Security control panel also allows developers to easily enable and disable the theft deterrence features. This way, a developer can test code with theft deterrence enabled when necessary. While this is also possible with 'enable-security' from the Open Firmware prompt, this will perform fewer safety checks, making it easier for a developer to inadvertently lock himself out of his machine.

Latest revision as of 03:25, 20 February 2022


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

What is a developer key?

A developer key is a file named develop.sig containing cryptographic information tied to a specific XO laptop that can be used by software to disable various security features.

See also Activation and developer keys.

Who uses developer keys?

Developer keys are requested and used by individual volunteers, developers, and testers. They are not intended to be used to customize XOs for large-scale OLPC deployments. Large-scale deployments work with OLPC to customize their build. See Developer key philosophy for the reasons why this feature was designed.

What do developer keys do?

Developer keys allow you to:

  • Install unsigned builds on your XO, such as builds from other deployments, or builds from active development, such as for build testing,
  • Upgrade the firmware independently of the versions included with signed builds, such as for firmware testing,
  • Work with the firmware, for diagnosis and repair, such as debricking,
  • Defeat the activation lease mechanism,
  • Gain full access on XOs that are bound to a deployment key.

Getting a developer key

Since developer keys are generated for each individual laptop when they are requested, you must first have a specific XO in mind that you want to unlock. Once you have chosen the XO you want to unlock, there are several ways of getting a key for it, listed here in order of preference. After you get your developer key, proceed to the Using a Developer Key section below.

If your XO is connected to the internet

This is by far the easiest and fastest method. If you can connect your running XO to a wifi access point or use a USB-to-wired ethernet adapter to get your XO online, please follow these instructions (the vast majority of developers use this method).

  1. On your XO, open the Browse activity and go to file:///home/.devkey.html. (In recent builds, "Get a developer key" is one of the links at the bottom of the Browse start page.)
  2. Follow the directions on that page to get a developer key.

Note that once your key has been created, you can return to this page in Browse at any time to re-download it.

If your XO is not connected to the internet

If your XO cannot be connected to the internet, but you have a USB storage device and access to a computer that is connected to the internet, you can copy the web page with the form to get a developer key to that computer:

  1. Copy the file /home/.devkey.html from your XO to the computer with internet access.
    • For example, entering the following command in the Terminal activity will copy the file you need to a USB device connected to your XO:
        cp -p /home/.devkey.html /var/run/media/*/devkey.html
  1. Open the devkey.html file in a browser on the computer with internet access and follow the directions on that page to get a developer key.

If you do not have internet access at all

This is very much not recommended, and extraordinarily rare, as most development work is done via email, chat, forums, and other internet-based communication mediums. However, if you must get a developer key and do not have access to the internet at all, 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 your XO does not boot

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.

If that doesn't work, see the Collection key page and follow the procedures there. When sending your email, please describe your problem, including the serial number (printed inside your battery compartment, visible when you remove the battery) in addition to attaching the laptops.dat file. If OLPC has a fix for the problem that prevents your laptop from booting properly, we will also send you other files to put on the USB flash drive to help to patch or circumvent it.

Getting developer keys for many XOs at once

Follow the instructions on the Collection key page.

Using a Developer Key

Note: This section and below needs a lot of work.' Mchua

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 flash drive; then, if you have trouble booting an unsigned OS image, you can boot with the USB flash drive inserted without having to clean-install.

What you can do

Once you have a developer key, you can choose to...

  1. By installing the developer key in /security/develop.sig, where it can be managed with the Security control panel (<trac>6428</trac>).
  2. By invoking 'disable-security' from the Open Firmware prompt to skip all key checking (until you invoke 'enable-security' again).

While this choice is left to the developer, the former option is recommended, because it exercises the key-checking and "pretty boot" code. This ensures that developers are regularly testing this code, so that any bugs can be quickly discovered and fixed--instead of making it to the machine of some poor six year old in Peru.

Using the Security control panel also allows developers to easily enable and disable the theft deterrence features. This way, a developer can test code with theft deterrence enabled when necessary. While this is also possible with 'enable-security' from the Open Firmware prompt, this will perform fewer safety checks, making it easier for a developer to inadvertently lock himself out of his machine.