1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
|
OLPC XO laptops can optionally include a security system, parts of which
aim to ensure the following:
1. Only trusted kernels and initramfs image (early boot code) can be booted
2. Only trusted OS images can be installed on the laptop
Trust is established through the verification of signatures of the above
components. The XO laptop flash includes a set of public keys which are used
to perform this verification.
These security systems are typically disabled for small deployments, but are
enabled for large deployments who have sufficient technical resources to
meet the technical challenges presented by this system. It's complex.
Other security systems are available too (e.g. developer keys,
activation leases) but these fall out of the scope of the tasks that
olpc-os-builder is concerned with.
See http://wiki.laptop.org/go/Firmware_security for more information. The
following instructions assume you understand the basics and know what you are
doing.
Some of the options below require you to have a local and ready-built checkout
of OLPC's bios-crypto git repository. You probably have one of these already,
because you've used this to create the keypairs that you'll be using for
signing, right? If not, instructions for this step can be found at
http://wiki.laptop.org/go/OSBuilder
Once you have done this, you should tell olpc-os-builder about this, as follows:
[signing]
bios_crypto_path=/home/myuser/bios-crypto
The above bios_crypto_path should point to the root directory of the git
checkout.
When following the instructions below, it is possible to combine a few steps.
For example, it is perfectly OK to configure olpc-os-builder to sign the
firmware, kernel, initramfs and resultant OS image all in the same build.
=== SIGNING KERNEL, INITRAMFS, AND FIRMWARE ===
These components must be signed and included in the OS build. There are
2 approaches that you can take here.
1. External signing
You can ask olpc-os-builder to extract various components from the build which
need signing, by enabling the "extract" option (default 0, disabled):
[signing]
extract=1
This causes an output file named osXX.for-signing.zip to be generated,
including all content needed for signing:
- an unsigned /boot/bootfw.zip is expected to be included in the build,
if found then this will be extracted
- if found, the kernel at /boot/vmlinuz will be extracted as an unsigned
runos.zip
- if found, the initramfs at /boot/initrd.img (or /boot/olpcrd.img) will be
extracted as an unsigned runrd.zip
You would then sign these components by your own means, perhaps on another
computer system, kept in a safe and never connected to any networks for
security purposes.
The output from this process should be some subset of the following files:
bootfw.zip - signed kernel
actos.zip - signed kernel for activation
runos.zip - signed kernel for regular boot
actrd.zip - signed initramfs for activation
runrd.zip - signed initramfs for regular boot
At this point, put all these zip files (without renaming them) into another
zip file, and run another build, this time with the following configuration:
[signing]
add_signed_content=/path/to/zip/file
The files from this zip file will be included in /boot in the final image.
It's OK to skip some files. act* and run* files will be created as symlinks
if they don't exist. For example, if you don't provide a actos.zip, a symlink
named "actos.zip" will be created, pointing at runos.zip. This is useful
when there is no difference between the signed content used for booting the
activation environment vs the regular system (as is true for all OLPC builds,
at the time of writing).
2. Signing at build time
If the keypairs are available at build time, you can sign these components
as part of the regular build process. bios-crypto is required here.
If you supply a 'w' key, the firmware found at /boot/bootfw.zip in your build
will be (re-)signed with that key.
If you supply an 'o' key, the kernel found at /boot/vmlinuz and the initramfs
found at /boot/initrd.img will be signed into runos.zip and runrd.zip
respectively, and actos/actrd symlinks will be set up.
If you supply both keys, the firmware, kernel and initramfs will all be signed.
This is usually what you want.
[signing]
bios_crypto_path=/home/myuser/bios-crypto
okey=/home/myuser/keys/o1
wkey=/home/myuser/keys/w1
In the above example, the root of the bios-crypto git checkout is at
/home/myuser/bios-crypto, and the public/private keys in question are found at:
/home/myuser/keys/o1.public
/home/myuser/keys/o1.private
/home/myuser/keys/w1.public
/home/myuser/keys/w1.private
=== SIGNING OS IMAGE ===
The 2nd step in the signing process is to sign the resultant OS image file,
allowing it to be used for NANDblaster and secure reflash. A similar pair
of options apply.
1. External signing
For XO-1.5, you need to sign the .zsp file that is produced as part of the
SD card image generation process. The following option will produce a fs.zip
file for every outputted .zsp file:
[signing]
make_zsp_fs_zip=1
A file named os31.2gb.zsp will result in os31.2gb.fs1.zip being generated
(the '1' in 'fs1' indicates XO-1.5).
For XO-1, bios-crypto is required. JFFS2 images (.img) are signed as follows:
[signing]
bios_crypto_path=/home/myuser/bios-crypto
make_img_fs_zip=1
All output jffs2 .img files will be signed into (e.g.) os52.fs0.zip.
And XO-1 UBIFS images (.onu alongside .uim) are signed as follows:
[signing]
bios_crypto_path=/home/myuser/bios-crypto
make_onu_fs_zip=1
All output ubifs .onu files will be signed into (e.g.) os52.onu.fs0.zip.
In all cases, these fs.zip output files are unsigned and must be externally
resigned using your private 's' key before it becomes useful.
2. Signing at build time
If the 's' keypair is available at build time, you can sign the resultant
build simply by specifying it's path in addition to following the instructions
above. bios-crypto is required in both cases.
e.g. for XO-1.5:
[signing]
bios_crypto_path=/home/myuser/bios-crypto
skey=/home/myuser/keys/s1
make_zsp_fs_zip=1
e.g. for XO-1:
[signing]
bios_crypto_path=/home/myuser/bios-crypto
skey=/home/myuser/keys/s1
make_img_fs_zip=1
make_onu_fs_zip=1
In both cases, the resultant fs.zip files will be signed with the 's' keypair,
whose files are expected to be found at:
/home/myuser/keys/s1.public
/home/myuser/keys/s1.private
|
