1fe013f8bSBen Hutchings=================== 2fe013f8bSBen HutchingsReproducible builds 3fe013f8bSBen Hutchings=================== 4fe013f8bSBen Hutchings 5fe013f8bSBen HutchingsIt is generally desirable that building the same source code with 6fe013f8bSBen Hutchingsthe same set of tools is reproducible, i.e. the output is always 7fe013f8bSBen Hutchingsexactly the same. This makes it possible to verify that the build 8fe013f8bSBen Hutchingsinfrastructure for a binary distribution or embedded system has not 9fe013f8bSBen Hutchingsbeen subverted. This can also make it easier to verify that a source 10fe013f8bSBen Hutchingsor tool change does not make any difference to the resulting binaries. 11fe013f8bSBen Hutchings 12fe013f8bSBen HutchingsThe `Reproducible Builds project`_ has more information about this 13fe013f8bSBen Hutchingsgeneral topic. This document covers the various reasons why building 14fe013f8bSBen Hutchingsthe kernel may be unreproducible, and how to avoid them. 15fe013f8bSBen Hutchings 16fe013f8bSBen HutchingsTimestamps 17fe013f8bSBen Hutchings---------- 18fe013f8bSBen Hutchings 1986cdd2fdSDmitry GoldinThe kernel embeds timestamps in three places: 20fe013f8bSBen Hutchings 21fe013f8bSBen Hutchings* The version string exposed by ``uname()`` and included in 22fe013f8bSBen Hutchings ``/proc/version`` 23fe013f8bSBen Hutchings 24fe013f8bSBen Hutchings* File timestamps in the embedded initramfs 25fe013f8bSBen Hutchings 2686cdd2fdSDmitry Goldin* If enabled via ``CONFIG_IKHEADERS``, file timestamps of kernel 2786cdd2fdSDmitry Goldin headers embedded in the kernel or respective module, 2886cdd2fdSDmitry Goldin exposed via ``/sys/kernel/kheaders.tar.xz`` 2986cdd2fdSDmitry Goldin 3086cdd2fdSDmitry GoldinBy default the timestamp is the current time and in the case of 3186cdd2fdSDmitry Goldin``kheaders`` the various files' modification times. This must 3286cdd2fdSDmitry Goldinbe overridden using the `KBUILD_BUILD_TIMESTAMP`_ variable. 3386cdd2fdSDmitry GoldinIf you are building from a git commit, you could use its commit date. 34fe013f8bSBen Hutchings 35fe013f8bSBen HutchingsThe kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros, 36fe013f8bSBen Hutchingsand enables warnings if they are used. If you incorporate external 37fe013f8bSBen Hutchingscode that does use these, you must override the timestamp they 38fe013f8bSBen Hutchingscorrespond to by setting the `SOURCE_DATE_EPOCH`_ environment 39fe013f8bSBen Hutchingsvariable. 40fe013f8bSBen Hutchings 41fe013f8bSBen HutchingsUser, host 42fe013f8bSBen Hutchings---------- 43fe013f8bSBen Hutchings 44fe013f8bSBen HutchingsThe kernel embeds the building user and host names in 45fe013f8bSBen Hutchings``/proc/version``. These must be overridden using the 46fe013f8bSBen Hutchings`KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables. If you are 47fe013f8bSBen Hutchingsbuilding from a git commit, you could use its committer address. 48fe013f8bSBen Hutchings 49fe013f8bSBen HutchingsAbsolute filenames 50fe013f8bSBen Hutchings------------------ 51fe013f8bSBen Hutchings 52fe013f8bSBen HutchingsWhen the kernel is built out-of-tree, debug information may include 53fe013f8bSBen Hutchingsabsolute filenames for the source files. This must be overridden by 54fe013f8bSBen Hutchingsincluding the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable. 55fe013f8bSBen Hutchings 56fe013f8bSBen HutchingsDepending on the compiler used, the ``__FILE__`` macro may also expand 57fe013f8bSBen Hutchingsto an absolute filename in an out-of-tree build. Kbuild automatically 58fe013f8bSBen Hutchingsuses the ``-fmacro-prefix-map`` option to prevent this, if it is 59fe013f8bSBen Hutchingssupported. 60fe013f8bSBen Hutchings 61fe013f8bSBen HutchingsThe Reproducible Builds web site has more information about these 62fe013f8bSBen Hutchings`prefix-map options`_. 63fe013f8bSBen Hutchings 64fe013f8bSBen HutchingsGenerated files in source packages 65fe013f8bSBen Hutchings---------------------------------- 66fe013f8bSBen Hutchings 67fe013f8bSBen HutchingsThe build processes for some programs under the ``tools/`` 68fe013f8bSBen Hutchingssubdirectory do not completely support out-of-tree builds. This may 69fe013f8bSBen Hutchingscause a later source package build using e.g. ``make rpm-pkg`` to 70fe013f8bSBen Hutchingsinclude generated files. You should ensure the source tree is 71fe013f8bSBen Hutchingspristine by running ``make mrproper`` or ``git clean -d -f -x`` before 72fe013f8bSBen Hutchingsbuilding a source package. 73fe013f8bSBen Hutchings 74fe013f8bSBen HutchingsModule signing 75fe013f8bSBen Hutchings-------------- 76fe013f8bSBen Hutchings 77fe013f8bSBen HutchingsIf you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to 78fe013f8bSBen Hutchingsgenerate a different temporary key for each build, resulting in the 79fe013f8bSBen Hutchingsmodules being unreproducible. However, including a signing key with 80fe013f8bSBen Hutchingsyour source would presumably defeat the purpose of signing modules. 81fe013f8bSBen Hutchings 82fe013f8bSBen HutchingsOne approach to this is to divide up the build process so that the 83fe013f8bSBen Hutchingsunreproducible parts can be treated as sources: 84fe013f8bSBen Hutchings 85fe013f8bSBen Hutchings1. Generate a persistent signing key. Add the certificate for the key 86fe013f8bSBen Hutchings to the kernel source. 87fe013f8bSBen Hutchings 88fe013f8bSBen Hutchings2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the 89fe013f8bSBen Hutchings signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an 90fe013f8bSBen Hutchings empty string, and disable ``CONFIG_MODULE_SIG_ALL``. 91fe013f8bSBen Hutchings Build the kernel and modules. 92fe013f8bSBen Hutchings 93fe013f8bSBen Hutchings3. Create detached signatures for the modules, and publish them as 94fe013f8bSBen Hutchings sources. 95fe013f8bSBen Hutchings 96fe013f8bSBen Hutchings4. Perform a second build that attaches the module signatures. It 97fe013f8bSBen Hutchings can either rebuild the modules or use the output of step 2. 98fe013f8bSBen Hutchings 99fe013f8bSBen HutchingsStructure randomisation 100fe013f8bSBen Hutchings----------------------- 101fe013f8bSBen Hutchings 102595b893eSKees CookIf you enable ``CONFIG_RANDSTRUCT``, you will need to pre-generate 103be2b34faSKees Cookthe random seed in ``scripts/basic/randstruct.seed`` so the same 104be2b34faSKees Cookvalue is used by each build. See ``scripts/gen-randstruct-seed.sh`` 105be2b34faSKees Cookfor details. 106fe013f8bSBen Hutchings 107fe013f8bSBen HutchingsDebug info conflicts 108fe013f8bSBen Hutchings-------------------- 109fe013f8bSBen Hutchings 110fe013f8bSBen HutchingsThis is not a problem of unreproducibility, but of generated files 111fe013f8bSBen Hutchingsbeing *too* reproducible. 112fe013f8bSBen Hutchings 113fe013f8bSBen HutchingsOnce you set all the necessary variables for a reproducible build, a 114fe013f8bSBen HutchingsvDSO's debug information may be identical even for different kernel 115fe013f8bSBen Hutchingsversions. This can result in file conflicts between debug information 116fe013f8bSBen Hutchingspackages for the different kernel versions. 117fe013f8bSBen Hutchings 118fe013f8bSBen HutchingsTo avoid this, you can make the vDSO different for different 119fe013f8bSBen Hutchingskernel versions by including an arbitrary string of "salt" in it. 120fe013f8bSBen HutchingsThis is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``. 121fe013f8bSBen Hutchings 122*114ff6feSDan LiGit 123*114ff6feSDan Li--- 124*114ff6feSDan Li 125*114ff6feSDan LiUncommitted changes or different commit ids in git can also lead 126*114ff6feSDan Lito different compilation results. For example, after executing 127*114ff6feSDan Li``git reset HEAD^``, even if the code is the same, the 128*114ff6feSDan Li``include/config/kernel.release`` generated during compilation 129*114ff6feSDan Liwill be different, which will eventually lead to binary differences. 130*114ff6feSDan LiSee ``scripts/setlocalversion`` for details. 131*114ff6feSDan Li 132fe013f8bSBen Hutchings.. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp 133fe013f8bSBen Hutchings.. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host 134fe013f8bSBen Hutchings.. _KCFLAGS: kbuild.html#kcflags 135fe013f8bSBen Hutchings.. _prefix-map options: https://reproducible-builds.org/docs/build-path/ 136fe013f8bSBen Hutchings.. _Reproducible Builds project: https://reproducible-builds.org/ 137fe013f8bSBen Hutchings.. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/ 138