Activation and developer keys: Difference between revisions
No edit summary |
|||
(96 intermediate revisions by 17 users not shown) | |||
Line 1: | Line 1: | ||
<noinclude>{{Google Translations}}</noinclude>{{OLPC}} |
|||
<noinclude>{{ GoogleTrans-en | es =show | bg =show | zh-CN =show | zh-TW =show | hr =show | cs =show | da =show | nl =show | fi =show | fr =show | de =show | el =show | hi =show | it =show | ja =show | ko =show | no =show | pl =show | pt =show | ro =show | ru =show | sv =show }}</noinclude> |
|||
{{OLPC}} |
|||
{{Developers}} |
|||
{{Translations}} |
{{Translations}} |
||
{{TOCright}} |
|||
{{Persisent-Developer-Key}} |
|||
A developer key is a file containing cryptographic information tied to a specific XO laptop. |
|||
* 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. |
|||
== 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. |
|||
* 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. |
|||
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. |
|||
* 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. |
|||
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. |
|||
* 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. |
|||
# 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.) |
|||
# 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. |
|||
== Is your laptop secured? == |
|||
===Disabling security=== |
|||
One of the commands you can enter will enable this situation permanently, even without a developer key. This process is reversible. |
|||
* [[G1G1 2007|Give One, Get One 2007]] and [[G1G1 2008|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 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 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. |
|||
#* 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 <tt>develop.sig</tt>). |
|||
#* Even if security is disabled, you can re-enable it for a single boot by [[Cheat codes|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. |
|||
== What the security system does == |
|||
==Getting a developer key for your running XO laptop== |
|||
* Unless the laptop is '''preactivated''', the system will only boot while it has a valid and non-expired '''activation'''. |
|||
# On the XO, open the [[Browse]] activity. |
|||
* 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). |
|||
# 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 (<trac>6314</trac> wonders if the library on the XO should be reorganized): |
|||
* The only firmware releases that can be installed are those that are signed by a trusted party. |
|||
#* In Ship.1, 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.) |
|||
* The only kernels and initramfs (boot code) that can be booted are those that are signed by a trusted party. |
|||
#* In newer builds (Update.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. |
|||
* You cannot gain access to Open Firmware's [[ok]] prompt. |
|||
#* In newer builds (Update.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" |
|||
#* You can also just type '''file:///home/.devkey.html''' in the browse location field to get to this form. |
|||
# Follow the directions to apply for a developer key. |
|||
# The key should be created within a day or two. |
|||
# Go back to the page when your key is ready, and follow the instructions for downloading your key. Once the key has been created, you can return to this page at any time to re-download it; there will be no further creation delay. |
|||
# 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. |
|||
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. |
|||
Tip for those of you, like me, who cannot read the small typeface used in the webpage returned by the activation server: copy the text and paste it into the Write activity, where you can resize it. (This not not necessary on newer builds that have copy/paste enabled in the Terminal activity.) |
|||
== Why you might want to unsecure your XO == |
|||
==Getting a developer key without WiFi== |
|||
OLPC and others produce unsigned [[OS images|operating system images]] for development and testing. These will only work on unsecured laptops. |
|||
You can do any of the following: |
|||
Various repair procedures, such as [[Fix clock|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|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 == |
|||
[[Image:Ok-xo-1-q2f19-secure-with-check-key-and-escape.png|thumb|300px|secured; coloured icons, and no "ok" prompt]] |
|||
* [[Shutdown]] the laptop, |
|||
* Hold down the '✓' (check) game pad key and turn on the laptop, |
|||
* Wait for the message ''Release the game keys to continue'', |
|||
* Hold down the Escape key (the top left key on the laptop keyboard, marked with [[File:Esc.png]] or "esc"), |
|||
* Release the '✓' (check) game pad key, and watch closely. |
|||
If a message ''Secured, continuing'' appears, or three coloured icons, the laptop is secured. |
|||
If the laptop boots the operating system, the laptop is secured. |
|||
<br clear="right"> |
|||
[[Image:Ok-xo-1-q2f19-unlocked-with-escape.png|thumb|300px|secured, but unlocked; an unlock icon, and an "ok" prompt]] |
|||
If a message ''Devel key Signature valid'' appears, and an icon corresponding to the device the developer key is on, then the laptop is secured, but unlocked by the developer key. |
|||
In this situation, you can disable security. |
|||
<br clear="right"> |
|||
[[Image:Ok-xo-1-q2f19-unsecure.png|thumb|300px|not secured, the "ok" prompt is present]] |
|||
If an "ok" prompt appears straight away like this, the laptop is not secured. |
|||
In this situation, you do not need a developer key. |
|||
<br clear="right"> |
|||
== Getting a developer key == |
|||
To get a developer key you will: |
|||
*get two numbers from the laptop, the serial number and the UUID, |
|||
*send these numbers to us, |
|||
*wait for up to 24 hours, |
|||
*receive the response. |
|||
We provide several ways to do this, as subsections below: |
|||
*[[#Getting_a_developer_key_using_a_USB_drive|using a special USB drive]], |
|||
*[[#Getting_a_developer_key_for_your_running_XO_laptop|using the web browser on the laptop]], |
|||
*[[#Getting_a_developer_key_without_WiFi|without wireless, using a USB ethernet adapter]], |
|||
*[[#Getting_a_developer_key_without_any_network_access|without network, using Terminal]], or |
|||
*[[#Getting_a_developer_key_by_postal_mail|by postal mail]]. |
|||
=== Getting a developer key using a USB drive === |
|||
A [[collection stick]] is a special USB drive that collects data so that you can request a developer key. See [[collection stick]] for how to prepare a USB drive and use it. |
|||
=== 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. |
|||
# 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. |
|||
# 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. |
|||
#* 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. |
|||
Next, [[#Using_a_developer_key|using a developer key]]. |
|||
''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. |
|||
==== 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+[[Image: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. |
|||
{{Activation.laptop.org}} |
|||
Next, on a computer that has web access and click on: [https://activation.laptop.org/devkey/post/ 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 without WiFi === |
|||
If you have wired network access, you can: |
|||
* 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. |
||
=== Getting a developer key without any network access === |
|||
* 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 /var/run/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 |
=== Getting a developer key by postal mail === |
||
You can write postal mail to OLPC, see the addresses on the [[OLPC:Contact_us|contact page]]. |
|||
=== If the machine won't boot === |
|||
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. |
|||
You must include your serial number, a return address, and that you are asking for a developer key. |
|||
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. |
|||
Your developer key will 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. |
|||
===Collecting serial numbers and UUID's for one or many XOs=== |
|||
Next, [[#Using_a_developer_key|using a developer key]]. |
|||
First, you must create a 'Collection stick': |
|||
== Using a developer key == |
|||
# 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. |
|||
# Put these files in a directory called 'boot' on a FAT-formatted or FAT32-formatted USB memory stick. |
|||
#* Most memory sticks use FAT or FAT32 when you buy them (except "U2" memory sticks which probably won't work; they contain ugly DRM stuff). |
|||
# So your USB memory stick will contain these files (and nothing else in the boot directory): |
|||
#*boot/ |
|||
#*boot/Actos.zip |
|||
#*boot/Runos.zip |
|||
# If there is an old laptops.dat file on the USB stick from an earlier collection of laptops, delete it. |
|||
#* The memory stick can have any other files on it that you like. |
|||
Our response will be a small file {{code|develop.sig}} containing a large number. When you give this file to the laptop in the right way, it will be temporarily unlocked. |
|||
Now, for each laptop that you want to get a Developer Key for (maybe only one): |
|||
=== Make back up copies! === |
|||
# Insert the 'Collection stick' in one of the USB ports on the laptop. |
|||
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 drive, if you have one. |
|||
# Power it on with the power key. |
|||
#* This will put your Serial Number and UUID into the <tt>laptops.dat</tt> file on the '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 the 'Collection stick'. |
|||
=== Where the developer key can be placed === |
|||
Do the above with each laptop in turn 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 laptops.dat file, so do not delete the laptops.dat file in between. |
|||
When the XO boots, its [[firmware]] checks to see if security is enabled or [[#Disable_the_security_system|permanently disabled]] (a system parameter). If it is enabled, it looks for the a developer key, at <tt>/security/develop.sig</tt>, on any USB flash drive or SD card that's plugged in, and on the internal storage. (See [[Firmware security]] for the details.) |
|||
When you're done, plug the 'Collector 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. |
|||
If that file is there and contains the right number, the XO will act as though it is unsecured: |
|||
Then wait for OLPC to send you your Developer key(s) and/or Activation key(s). |
|||
* You will be able to interrupt the boot process and enter commands, |
|||
* You can run any compatible operating system, not only the signed operating system, |
|||
* You will be able to disable the security permanently. |
|||
=== Disabling the security system=== |
|||
=== What to do when you receive your activation or developer keys === |
|||
Once you have a developer key: |
|||
* Make sure it is in the <tt>/security/</tt> directory on your USB drive or SD card. |
|||
# You can use the same USB memory stick 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. |
|||
* Plug it into your XO before booting it. Boot your XO with that drive/card plugged in. |
|||
# You'll receive one or two files from OLPC, probably by email. Extract the file or files using your email program. |
|||
* 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.) |
|||
# If you receive a <tt>lease.sig</tt> 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 memory stick. |
|||
# Make a directory called <tt>security</tt> in the root directory of your USB memory stick. |
|||
# Copy the developer key (<tt>develop.sig</tt>) into the <tt>security</tt> directory on the USB memory stick. |
|||
#* When you're done, these files will be there: |
|||
#**lease.sig (only if received) |
|||
#**security/ |
|||
#**security/develop.sig |
|||
# OLPC may also send you other files to put on the memory stick, e.g. to help to patch or circumvent whatever problem is preventing your laptop from booting properly. |
|||
# With the laptop powered off, insert the USB memory stick in one of its USB ports. |
|||
# Power on the laptop. |
|||
# 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. |
|||
# 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. |
|||
#* To permanently disable secure boot, press Escape and see the above, [[#Disabling Security|Disabling Security]]. |
|||
# 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 <tt>security/develop.sig</tt> from the USB memory stick into <tt>/security/develop.sig</tt> in the root filesystem of the laptop. You'll need a root shell to do that; it can't be done from the Journal or the GUI. |
|||
# If the laptop is running Linux, go into the Journal, position the mouse over the USB stick 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 stick image any more. Then it's safe to remove the USB stick from that laptop. |
|||
# If the laptop is at an "ok" prompt in the boot firmware, it's safe to remove the USB stick immediately. |
|||
To '''permanently turn off firmware security''': |
|||
If you submitted information for more than one laptop, you can then put the USB memory stick into the |
|||
* Boot the XO as above, with a USB drive or SD card with the developer key plugged in. Interrupt the boot sequence: press the [[File:Esc.png]] ''Escape'' key a few times during the startup sound, just after turning the laptop on, to bring up the firmware [[Ok|Ok prompt]]. (for other ways to reach the prompt, see [[Ok prompt]].) |
|||
next laptop, and repeat the above process. The same memory stick, with the same lease.sig and develop.sig files, should work for all the laptops you included in the laptops.dat file. |
|||
* Type <tt>''disable-security''</tt>. Press enter. |
|||
# If ''disable-security'' says "No wp tag", it means that security is already disabled. |
|||
#: |
|||
# 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 [[Cheat codes|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 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 [[upgrading firmware]], or try using an SD card instead. It should be vfat formatted, for which you can use ''gparted''. |
|||
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 [[Image:Esc.png]] -- then you will get to an [[ok]] prompt |
|||
type: |
|||
<pre> |
|||
disable-security |
|||
</pre> |
|||
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. |
|||
Now you can reboot and take out the SD card if you hit [[Image: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 <tt>/security/develop.sig</tt>. |
|||
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: |
|||
* Ask us for the developer key again, and there won't be a 24 hour delay. |
|||
* 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 <tt>/security/develop.sig</tt> (this is why you should always be sure to backup <tt>develop.sig</tt>), 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 Activity|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. |
|||
== See also == |
== See also == |
||
Line 118: | Line 197: | ||
* [[olpc-update]] |
* [[olpc-update]] |
||
* [[Updates]] |
* [[Updates]] |
||
* [[Software update]] |
|||
''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.'' |
''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.'' |
||
[[Category:Developers]] [[Category:Firmware]] [[Category:Copyright]] [[Category:OLPC FAQ]] [[Category:OS]] [[Category:Security]] [[Category:Software development]] [[Category:Repair]] [[Category:Wiki pages that XO content links to]] |
|||
[[Category:Developers]] [[Category:Firmware]] [[Category:Licensing]] [[Category:OLPC FAQ]] [[Category:OS]] [[Category:Security]] [[Category:Software development]] [[Category:Repair]] [[Category:Wiki pages that XO content links to]] |
Latest revision as of 02:22, 2 October 2021
Note: as of October 2021, OLPC has released Persistent developer key firmware to disable the activation and developer key system on a laptop.
- 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.
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
- Shutdown the laptop,
- Hold down the '✓' (check) game pad key and turn on the laptop,
- Wait for the message Release the game keys to continue,
- Hold down the Escape key (the top left key on the laptop keyboard, marked with
or "esc"),
- Release the '✓' (check) game pad key, and watch closely.
If a message Secured, continuing appears, or three coloured icons, the laptop is secured.
If the laptop boots the operating system, the laptop is secured.
If a message Devel key Signature valid appears, and an icon corresponding to the device the developer key is on, then the laptop is secured, but unlocked by the developer key.
In this situation, you can disable security.
If an "ok" prompt appears straight away like this, the laptop is not secured.
In this situation, you do not need a developer key.
Getting a developer key
To get a developer key you will:
- get two numbers from the laptop, the serial number and the UUID,
- send these numbers to us,
- wait for up to 24 hours,
- receive the response.
We provide several ways to do this, as subsections below:
- using a special USB drive,
- using the web browser on the laptop,
- without wireless, using a USB ethernet adapter,
- without network, using Terminal, or
- by postal mail.
Getting a developer key using a USB drive
A collection stick is a special USB drive that collects data so that you can request a developer key. See collection stick for how to prepare a USB drive and use it.
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.
- 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.
- 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.
- 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.
Next, using a developer key.
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.
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+ 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 without WiFi
If you have wired network access, you can:
- use a USB-to-wired ethernet adapter to get your XO on the net, then follow the above instructions.
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
Getting a developer key by postal mail
You can write postal mail to OLPC, see the addresses on the contact page.
You must include your serial number, a return address, and that you are asking for a developer key.
Your developer key will 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.
Next, using a developer key.
Using a developer key
Our response will be a small file develop.sig containing a large number. When you give this file to the laptop in the right way, it will be temporarily unlocked.
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.
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 storage. (See Firmware security for the details.)
If that file is there and contains the right number, 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 compatible operating system, not only the signed operating system,
- You will be able to disable the security permanently.
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
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.
- If disable-security says "No wp tag", it means that security is already disabled.
- 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 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 upgrading firmware, or try using an SD card instead. It should be vfat formatted, for which you can use gparted.
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 -- 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.
Now you can reboot and take out the SD card if you hit 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:
- Ask us for the developer key again, and there won't be a 24 hour delay.
- 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.
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.