Collection stick: Difference between revisions
(in current version the file is not in /boot on the USB key) |
No edit summary |
||
(46 intermediate revisions by 7 users not shown) | |||
Line 1: | Line 1: | ||
{{Persisent-Developer-Key}} |
|||
== Making a collection key == |
|||
<noinclude>{{TOCright}} |
|||
You'll need a FAT-formatted or FAT32-formatted USB storage device for this, as well as a computer with internet access. The USB storage device does not need to be empty. |
|||
[[Category:Firmware]] |
|||
[[Category:Security]] |
|||
[[Category:Deployment]] |
|||
<noinclude> |
|||
A [[Collection stick]] is a USB drive with a program on it that collects data in order to request [[developer key|developer keys]]. Developer keys are the unique cryptographic signatures for XO laptops that permit access to the system [[Firmware|firmware]]. |
|||
# Create a <code>/boot</code> directory in the root of your USB storage device. If such a directory already exists, it should be empty. (Exception: if you have already used this collector key to gather data from a number of XOs, there may be a <code>laptops.dat</code> file in the <code>/boot</code> directory. Do not delete <code>laptops.dat</code>.) |
|||
# On the computer with internet access, [[media:Actos.zip|Actos.zip]] and [[media:Runos.zip|Runos.zip]] [http://dev.laptop.org/git?p=users/cscott/actkey (source code)] into that <code>/boot</code> directory. You should now have 2 files (3, if you have <code>laptops.dat</code> in a <code>/boot</code> directory on the root of your USB storage device. |
|||
What you will need: |
|||
== Collecting with a collection key == |
|||
* a [[USB drive]], to be used as a Collection stick, |
|||
* a second [[USB drive]], to be used as an Unlock stick, |
|||
* a computer with Internet access, and; |
|||
* the group of XO laptops, which may be nearby or distant. |
|||
What you do is: |
|||
* [[#Emptying|empty the USB drives]], |
|||
* [[#Making|make a collection stick]], |
|||
* [[#Collecting|use the collection stick]] on the group of XO laptops, |
|||
* [[#Request_keys|request the keys]] using the data on the collection stick, |
|||
* [[#Receive_keys|receive the keys]], |
|||
* [[#Unlock_stick|make an unlock stick]] using the files received, |
|||
* [[#Unlocking|use the unlock stick]] on the group of XO laptops. |
|||
== Emptying == |
|||
# Make sure the XO is powered off. |
|||
# Plug the USB storage device into the XO, then power it on. |
|||
# You will see a graphical "XO" screen and then a short message like "SHFxxxxxxxx nnnnnnnnnnnnnnn; Laptop data recorded successfully". The XO will then power itself off or otherwise indicate that it is done. |
|||
# Remove the USB storage device from the XO. |
|||
Choose two USB drives and label them temporarily, as ''Collection stick'' and ''Unlock stick''. |
|||
When you have finished this process on all the XOs you need developer keys for, plug the USB storage device into the computer with internet access and attach the <code>/laptops.dat</code> file from the USB storage device to an email to <code> help at laptop dot org </code> indicating whether you want a [[developer key]] or an [[activation key]]. |
|||
Note: you can use one USB drive for both purposes, but be very careful to empty the USB drive before using it as Unlock stick. |
|||
== Making an unlock key == |
|||
The size of the USB drives is not important. |
|||
You will receive back one or two files from OLPC after submitting your <code>laptops.dat</code> file (this may take several days). Here is what to do once you get these files. |
|||
USB flash drives are normally sold with a DOS MBR partition table and a FAT filesystem, and this is sufficient. See [[Firmware/Storage/Formats|more details]]. You may wish to verify that each USB drive has: |
|||
# Get a USB storage device. This can be your old collection key; you will have to rename the <tt>/boot</tt> directory to something else like <tt>/collection</tt>. If you don't do this, your laptop will just re-run the collection script. |
|||
# '''If you requested a developer key:''' You will get a file called <tt>'''develop.sig'''</tt>. Make a directory called <tt>'''security/'''</tt> in the root directory of your USB storage device and copy this file into it. |
|||
# '''If you requested an activation key:''' You will get a file called <tt>'''lease.sig'''</tt>. Copy this file into the root directory of your USB storage device. |
|||
* a DOS MBR partition table, and if not choose other USB drives or recreate the partition table, |
|||
You are now ready to use your unlock key. |
|||
* a FAT, ext2 or ext3 filesystem, and if not reformat to FAT, |
|||
Next, backup any files from the USB drive that you want to keep. In particular, for the purposes of a Collection stick and Unlock stick, you must: |
|||
== Unlocking with an unlock key == |
|||
* Delete any file with name {{Code|laptops.dat}} left over from previous use, |
|||
For each XO you are trying to unlock: |
|||
* Delete any directory with name {{Code|boot}}. |
|||
== Making == |
|||
# Make sure the XO is powered off. |
|||
# Plug the USB storage device into the XO, then power it on. |
|||
# That's it! |
|||
# Note that this process only unlocks your XO once - if you want to unlock your XO permanently without needing to plug in the USB storage device every time you boot, see [[#Permanently unlocking with an unlock key]]. |
|||
On the computer with Internet access: |
|||
== Permanently unlocking with an unlock key == |
|||
# Insert the USB drive to be used as Collection stick, |
|||
# Create a new directory with name {{Code|boot}} in the top level of your USB drive. |
|||
# Download [[media:Actos.zip|Actos.zip]] and [[media:Runos.zip|Runos.zip]] into that {{Code|boot}} directory. |
|||
You should now have a USB drive containing a directory {{Code|boot}} which contains two files {{Code|Actos.zip}}, and {{Code|Runos.zip}}. This is a collection stick ready to use. |
|||
== Collecting == |
|||
For each XO in the group: |
|||
* make sure the laptop is off, (e.g. check for a blinking power indicator), |
|||
* plug the Collection stick USB drive into the laptop, |
|||
* turn on the laptop, |
|||
* wait about ten seconds for a short message that looks like this: |
|||
SHC016013D1 {{CURRENTYEAR}}{{CURRENTMONTH}}{{CURRENTDAY}}T{{CURRENTHOUR}}{{CURRENTMINUTE}}{{CURRENTSECOND}}Z |
|||
Laptop data recorded successfully. |
|||
Powering off ... |
|||
* wait for the laptop to turn off, |
|||
* remove the USB drive from the laptop. |
|||
(The collection stick may do nothing if the laptop is unlocked already, if so hold the '×' game pad key to force "secure" booting.) |
|||
When you have done this on all the XOs you need keys for, move to the next step below. |
|||
== Request keys == |
|||
Plug the Collection stick USB drive into the computer with Internet access. |
|||
{{Activation.laptop.org}} |
|||
For individuals and small groups: |
|||
* open {{Code|laptops.dat}} and you will find one line for each laptop, with three values separated by spaces; the first is a serial number, the second is a [http://en.wikipedia.org/wiki/Universally_unique_identifier UUID], and the third is the date and time from the laptop clock, |
|||
* visit the web page [http://activation.laptop.org/devkey/post/ OLPC Activation Service], and enter the serial number and the UUID, and click on ''Request developer key'', |
|||
* follow the instructions on that web page to download the developer key, |
|||
* add each of the developer keys into a new file, and name it {{Code|develop.sig}}. |
|||
For larger groups: |
|||
* attach the {{Code|laptops.dat}} file from the USB drive to an email to [[User:Quozl|James Cameron]] at <tt>[mailto:quozl@laptop.org quozl@laptop.org]</tt> or your OLPC or deployment contact, |
|||
For small requests, the response from the OLPC Activation Service will be either: |
|||
* 24 hours, if this is the first request for a laptop, or; |
|||
* immediate, if a request was already made for a laptop. |
|||
For larger requests, the response from OLPC may take several days. |
|||
== Receive keys == |
|||
You will receive back one or two files from OLPC after submitting your {{Code|laptops.dat}} file. |
|||
# '''If you requested a developer key:''' You will get a file called {{Code|develop.sig}}. It contains a developer key for each laptop. |
|||
# '''If you requested an activation key:''' You will get a file called {{Code|lease.sig}}. It contains an activation key for each laptop. |
|||
You are now ready to make an unlock stick. |
|||
== Unlock stick == |
|||
# Insert the USB drive to be used as an Unlock stick, |
|||
# If you are using the same USB drive, [[#Emptying|empty it]], in particular remove the file {{Code|laptops.dat}} and the directory {{Code|boot}}, |
|||
# If you have received a file called {{Code|develop.sig}}, make a directory called {{Code|security}} at the top of the USB drive and copy this file into it. |
|||
# If you have received a file called {{Code|lease.sig}}, copy this file into the top of the USB drive. |
|||
You should now have a USB drive containing either a directory {{Code|security}} which contains {{Code|develop.sig}}, or {{Code|lease.sig}} in the top of the drive. This is an unlock stick ready to use. |
|||
== Unlocking == |
|||
For each XO in the group: |
|||
# Make sure the XO is powered off. |
|||
# Plug the Unlock stick USB drive into the XO, then power it on. |
|||
That's it! |
|||
Note that this process only unlocks your XO for one boot - if you want to unlock your XO permanently without needing to plug in the USB drive every time you boot, see [[#Permanently unlocking with an Unlock stick]]. |
|||
=== Activation keys === |
=== Activation keys === |
||
No action is required. Activation keys are automatically copied to |
No action is required. Activation keys are automatically copied to {{Code|/security/lease.sig}} on your XO. Keep the activation key around (or copy it to your School Server) in case you later need to reflash the XO. |
||
=== Developer keys === |
=== Developer keys === |
||
A laptop will boot normally with a developer key present; you have to do an extra step to take full command: |
|||
When the XO boots the first time, you should see a textual 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. |
|||
[[Image:Ok-xo-1-q2f19-unlocked-with-escape.png|thumb|secured, but unlocked with a developer key on USB drive]] |
|||
* [[Shutdown]] the laptop, |
|||
* Insert the USB drive or SD card containing the developer key, or with the key on the internal storage, |
|||
* Hold down the '✓' (check) game pad key and turn on the laptop, a diagram of the game keys should appear with a message ''Release the game keys to continue'', |
|||
* Release the '✓' (check) game pad key, and within ten seconds a ''Devel key Signature valid'' message will appear, with an open padlock icon, followed by ''Type the ESC key to interrupt automatic startup'', |
|||
* Press [[File:Esc.png]] ''Escape'' key once, and the 'ok' prompt should appear immediately. |
|||
The laptop is now unlocked temporarily. |
|||
== Permanently unlocking with an Unlock stick == |
|||
To permanently disable secure booting on each laptop, change the Unlock stick: |
|||
* create a {{Code|boot}} directory, and open it, |
|||
* add this text to a file {{Code|olpc.fth}}: |
|||
\ Open Firmware |
|||
disable-security |
|||
* check that the {{Code|olpc.fth}} file is in the {{Code|boot}} directory. |
|||
Then insert the changed Unlock stick into each laptop and turn it on. Watch. The laptop will reboot once or twice. Wait for the [[Ok]] prompt to appear on screen. The laptop is now unlocked permanently. |
|||
(It works like this; when the laptop turns on, it searches for the {{Code|security/develop.sig}} file, validates it, then switches to unsecure mode, then searches for the {{Code|boot/olpc.fth}} file and runs it. The {{Code|boot/olpc.fth}} contains the {{Code|disable-security}} command, which disables the security system and reboots. On the second boot, with the security system already disabled, {{Code|disable-security}} does nothing, and so the [[Ok]] prompt appears.) |
|||
You can also do this manually by inserting the Unlock stick, obtaining the [[Ok]] prompt, and then typing {{Code|disable-security}} once or twice. See [[Activation_and_developer_keys#Disabling_the_security_system|Activation and developer keys]] for more detail. |
|||
Once you do this, you will not need the Developer key on the laptop, but you can keep it in case security is ever enabled. |
|||
== Remote Support == |
|||
See [[Collection_stick/0|the remote support procedure for unlocking a laptop]]. |
|||
When providing remote support for the owner of a laptop, properly creating directories and files may be a challenge. To alleviate this, prepare a {{Code|.zip}} file for them to unpack onto their USB drive: |
|||
* make a directory to work in, |
|||
* make the directories and files that they would have to make, |
|||
* make a {{Code|.zip}} of the working directory, |
|||
* check the {{Code|.zip}} file carefully, |
|||
* send the file and ask the owner to expand it on a USB drive, insert it in the laptop, power on, and tell you what happens. |
|||
For example: we made [[media:CollectionStick.zip|CollectionStick.zip]], with {{Code|boot}} and {{Code|security}} directories, with the {{Code|Actos.zip}}, {{Code|Runos.zip}} and {{Code|olpc.fth}} files already properly placed. It can be used as part of an e-mail exchange with an owner. See [[Collection_stick/0|how to use it]]. |
|||
== Unlocking only until the next reinstall or upgrade == |
|||
The firmware checks for the Developer key on all available storage, which is why an Unlock stick works the way it does. But this means you would need to keep the Unlock stick handy to use it. |
|||
Alternatively, you can copy Developer key to your laptop's internal flash memory. Copy {{Code|security/develop.sig}} from the USB drive into {{Code|/security/develop.sig}} on the XO. In a [[Terminal activity]] type: |
|||
sudo cp /run/media/olpc/USBDRIVE/security/develop.sig /security/develop.sig |
|||
Where USBDRIVE is the volume label of the USB drive. |
|||
*(Note that {{Code|/media}} was used instead of {{Code|/run/media/olpc}} before 12.1.0). |
|||
== See Also == |
|||
To permanently disable secure booting, press ''Escape'' and type "<tt>disable-security</tt>", then power cycle and repeat that command. |
|||
*[http://dev.laptop.org/git/users/cscott/actkey source code] |
|||
The developer key is not automatically copied to your laptop's internal flash memory. You can do that by copying <tt>security/develop.sig</tt> from the USB flash drive into <tt>'''/security/develop.sig'''</tt> on the XO. You'll need to be [[root]] in a [[Terminal activity]] to do that. |
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 Collection stick is a USB drive with a program on it that collects data in order to request developer keys. Developer keys are the unique cryptographic signatures for XO laptops that permit access to the system firmware.
What you will need:
- a USB drive, to be used as a Collection stick,
- a second USB drive, to be used as an Unlock stick,
- a computer with Internet access, and;
- the group of XO laptops, which may be nearby or distant.
What you do is:
- empty the USB drives,
- make a collection stick,
- use the collection stick on the group of XO laptops,
- request the keys using the data on the collection stick,
- receive the keys,
- make an unlock stick using the files received,
- use the unlock stick on the group of XO laptops.
Emptying
Choose two USB drives and label them temporarily, as Collection stick and Unlock stick.
Note: you can use one USB drive for both purposes, but be very careful to empty the USB drive before using it as Unlock stick.
The size of the USB drives is not important.
USB flash drives are normally sold with a DOS MBR partition table and a FAT filesystem, and this is sufficient. See more details. You may wish to verify that each USB drive has:
- a DOS MBR partition table, and if not choose other USB drives or recreate the partition table,
- a FAT, ext2 or ext3 filesystem, and if not reformat to FAT,
Next, backup any files from the USB drive that you want to keep. In particular, for the purposes of a Collection stick and Unlock stick, you must:
- Delete any file with name laptops.dat left over from previous use,
- Delete any directory with name boot.
Making
On the computer with Internet access:
- Insert the USB drive to be used as Collection stick,
- Create a new directory with name boot in the top level of your USB drive.
- Download Actos.zip and Runos.zip into that boot directory.
You should now have a USB drive containing a directory boot which contains two files Actos.zip, and Runos.zip. This is a collection stick ready to use.
Collecting
For each XO in the group:
- make sure the laptop is off, (e.g. check for a blinking power indicator),
- plug the Collection stick USB drive into the laptop,
- turn on the laptop,
- wait about ten seconds for a short message that looks like this:
SHC016013D1 20240824T204348Z Laptop data recorded successfully. Powering off ...
- wait for the laptop to turn off,
- remove the USB drive from the laptop.
(The collection stick may do nothing if the laptop is unlocked already, if so hold the '×' game pad key to force "secure" booting.)
When you have done this on all the XOs you need keys for, move to the next step below.
Request keys
Plug the Collection stick USB drive into the computer with Internet access.
For individuals and small groups:
- open laptops.dat and you will find one line for each laptop, with three values separated by spaces; the first is a serial number, the second is a UUID, and the third is the date and time from the laptop clock,
- visit the web page OLPC Activation Service, and enter the serial number and the UUID, and click on Request developer key,
- follow the instructions on that web page to download the developer key,
- add each of the developer keys into a new file, and name it develop.sig.
For larger groups:
- attach the laptops.dat file from the USB drive to an email to James Cameron at quozl@laptop.org or your OLPC or deployment contact,
For small requests, the response from the OLPC Activation Service will be either:
- 24 hours, if this is the first request for a laptop, or;
- immediate, if a request was already made for a laptop.
For larger requests, the response from OLPC may take several days.
Receive keys
You will receive back one or two files from OLPC after submitting your laptops.dat file.
- If you requested a developer key: You will get a file called develop.sig. It contains a developer key for each laptop.
- If you requested an activation key: You will get a file called lease.sig. It contains an activation key for each laptop.
You are now ready to make an unlock stick.
Unlock stick
- Insert the USB drive to be used as an Unlock stick,
- If you are using the same USB drive, empty it, in particular remove the file laptops.dat and the directory boot,
- If you have received a file called develop.sig, make a directory called security at the top of the USB drive and copy this file into it.
- If you have received a file called lease.sig, copy this file into the top of the USB drive.
You should now have a USB drive containing either a directory security which contains develop.sig, or lease.sig in the top of the drive. This is an unlock stick ready to use.
Unlocking
For each XO in the group:
- Make sure the XO is powered off.
- Plug the Unlock stick USB drive into the XO, then power it on.
That's it! Note that this process only unlocks your XO for one boot - if you want to unlock your XO permanently without needing to plug in the USB drive every time you boot, see #Permanently unlocking with an Unlock stick.
Activation keys
No action is required. Activation keys are automatically copied to /security/lease.sig on your XO. Keep the activation key around (or copy it to your School Server) in case you later need to reflash the XO.
Developer keys
A laptop will boot normally with a developer key present; you have to do an extra step to take full command:
- Shutdown the laptop,
- Insert the USB drive or SD card containing the developer key, or with the key on the internal storage,
- Hold down the '✓' (check) game pad key and turn on the laptop, a diagram of the game keys should appear with a message Release the game keys to continue,
- Release the '✓' (check) game pad key, and within ten seconds a Devel key Signature valid message will appear, with an open padlock icon, followed by Type the ESC key to interrupt automatic startup,
- Press
Escape key once, and the 'ok' prompt should appear immediately.
The laptop is now unlocked temporarily.
Permanently unlocking with an Unlock stick
To permanently disable secure booting on each laptop, change the Unlock stick:
- create a boot directory, and open it,
- add this text to a file olpc.fth:
\ Open Firmware disable-security
- check that the olpc.fth file is in the boot directory.
Then insert the changed Unlock stick into each laptop and turn it on. Watch. The laptop will reboot once or twice. Wait for the Ok prompt to appear on screen. The laptop is now unlocked permanently.
(It works like this; when the laptop turns on, it searches for the security/develop.sig file, validates it, then switches to unsecure mode, then searches for the boot/olpc.fth file and runs it. The boot/olpc.fth contains the disable-security command, which disables the security system and reboots. On the second boot, with the security system already disabled, disable-security does nothing, and so the Ok prompt appears.)
You can also do this manually by inserting the Unlock stick, obtaining the Ok prompt, and then typing disable-security once or twice. See Activation and developer keys for more detail.
Once you do this, you will not need the Developer key on the laptop, but you can keep it in case security is ever enabled.
Remote Support
See the remote support procedure for unlocking a laptop.
When providing remote support for the owner of a laptop, properly creating directories and files may be a challenge. To alleviate this, prepare a .zip file for them to unpack onto their USB drive:
- make a directory to work in,
- make the directories and files that they would have to make,
- make a .zip of the working directory,
- check the .zip file carefully,
- send the file and ask the owner to expand it on a USB drive, insert it in the laptop, power on, and tell you what happens.
For example: we made CollectionStick.zip, with boot and security directories, with the Actos.zip, Runos.zip and olpc.fth files already properly placed. It can be used as part of an e-mail exchange with an owner. See how to use it.
Unlocking only until the next reinstall or upgrade
The firmware checks for the Developer key on all available storage, which is why an Unlock stick works the way it does. But this means you would need to keep the Unlock stick handy to use it.
Alternatively, you can copy Developer key to your laptop's internal flash memory. Copy security/develop.sig from the USB drive into /security/develop.sig on the XO. In a Terminal activity type:
sudo cp /run/media/olpc/USBDRIVE/security/develop.sig /security/develop.sig
Where USBDRIVE is the volume label of the USB drive.
- (Note that /media was used instead of /run/media/olpc before 12.1.0).