Commit | Line | Data |
---|---|---|
fe013f8b BH |
1 | =================== |
2 | Reproducible builds | |
3 | =================== | |
4 | ||
5 | It is generally desirable that building the same source code with | |
6 | the same set of tools is reproducible, i.e. the output is always | |
7 | exactly the same. This makes it possible to verify that the build | |
8 | infrastructure for a binary distribution or embedded system has not | |
9 | been subverted. This can also make it easier to verify that a source | |
10 | or tool change does not make any difference to the resulting binaries. | |
11 | ||
12 | The `Reproducible Builds project`_ has more information about this | |
13 | general topic. This document covers the various reasons why building | |
14 | the kernel may be unreproducible, and how to avoid them. | |
15 | ||
16 | Timestamps | |
17 | ---------- | |
18 | ||
86cdd2fd | 19 | The kernel embeds timestamps in three places: |
fe013f8b BH |
20 | |
21 | * The version string exposed by ``uname()`` and included in | |
22 | ``/proc/version`` | |
23 | ||
24 | * File timestamps in the embedded initramfs | |
25 | ||
86cdd2fd DG |
26 | * If enabled via ``CONFIG_IKHEADERS``, file timestamps of kernel |
27 | headers embedded in the kernel or respective module, | |
28 | exposed via ``/sys/kernel/kheaders.tar.xz`` | |
29 | ||
30 | By default the timestamp is the current time and in the case of | |
31 | ``kheaders`` the various files' modification times. This must | |
32 | be overridden using the `KBUILD_BUILD_TIMESTAMP`_ variable. | |
33 | If you are building from a git commit, you could use its commit date. | |
fe013f8b BH |
34 | |
35 | The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, | |
36 | and enables warnings if they are used. If you incorporate external | |
37 | code that does use these, you must override the timestamp they | |
38 | correspond to by setting the `SOURCE_DATE_EPOCH`_ environment | |
39 | variable. | |
40 | ||
41 | User, host | |
42 | ---------- | |
43 | ||
44 | The kernel embeds the building user and host names in | |
45 | ``/proc/version``. These must be overridden using the | |
46 | `KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables. If you are | |
47 | building from a git commit, you could use its committer address. | |
48 | ||
49 | Absolute filenames | |
50 | ------------------ | |
51 | ||
52 | When the kernel is built out-of-tree, debug information may include | |
53 | absolute filenames for the source files. This must be overridden by | |
54 | including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable. | |
55 | ||
56 | Depending on the compiler used, the ``__FILE__`` macro may also expand | |
57 | to an absolute filename in an out-of-tree build. Kbuild automatically | |
58 | uses the ``-fmacro-prefix-map`` option to prevent this, if it is | |
59 | supported. | |
60 | ||
61 | The Reproducible Builds web site has more information about these | |
62 | `prefix-map options`_. | |
63 | ||
64 | Generated files in source packages | |
65 | ---------------------------------- | |
66 | ||
67 | The build processes for some programs under the ``tools/`` | |
68 | subdirectory do not completely support out-of-tree builds. This may | |
69 | cause a later source package build using e.g. ``make rpm-pkg`` to | |
70 | include generated files. You should ensure the source tree is | |
71 | pristine by running ``make mrproper`` or ``git clean -d -f -x`` before | |
72 | building a source package. | |
73 | ||
74 | Module signing | |
75 | -------------- | |
76 | ||
77 | If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to | |
78 | generate a different temporary key for each build, resulting in the | |
79 | modules being unreproducible. However, including a signing key with | |
80 | your source would presumably defeat the purpose of signing modules. | |
81 | ||
82 | One approach to this is to divide up the build process so that the | |
83 | unreproducible parts can be treated as sources: | |
84 | ||
85 | 1. Generate a persistent signing key. Add the certificate for the key | |
86 | to the kernel source. | |
87 | ||
88 | 2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the | |
89 | signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an | |
90 | empty string, and disable ``CONFIG_MODULE_SIG_ALL``. | |
91 | Build the kernel and modules. | |
92 | ||
93 | 3. Create detached signatures for the modules, and publish them as | |
94 | sources. | |
95 | ||
96 | 4. Perform a second build that attaches the module signatures. It | |
97 | can either rebuild the modules or use the output of step 2. | |
98 | ||
99 | Structure randomisation | |
100 | ----------------------- | |
101 | ||
595b893e KC |
102 | If you enable ``CONFIG_RANDSTRUCT``, you will need to pre-generate |
103 | the random seed in ``scripts/gcc-plugins/randomize_layout_seed.h`` | |
104 | so the same value is used in rebuilds. | |
fe013f8b BH |
105 | |
106 | Debug info conflicts | |
107 | -------------------- | |
108 | ||
109 | This is not a problem of unreproducibility, but of generated files | |
110 | being *too* reproducible. | |
111 | ||
112 | Once you set all the necessary variables for a reproducible build, a | |
113 | vDSO's debug information may be identical even for different kernel | |
114 | versions. This can result in file conflicts between debug information | |
115 | packages for the different kernel versions. | |
116 | ||
117 | To avoid this, you can make the vDSO different for different | |
118 | kernel versions by including an arbitrary string of "salt" in it. | |
119 | This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``. | |
120 | ||
121 | .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp | |
122 | .. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host | |
123 | .. _KCFLAGS: kbuild.html#kcflags | |
124 | .. _prefix-map options: https://reproducible-builds.org/docs/build-path/ | |
125 | .. _Reproducible Builds project: https://reproducible-builds.org/ | |
126 | .. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/ |