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