0001 ===================
0002 Reproducible builds
0003 ===================
0004
0005 It is generally desirable that building the same source code with
0006 the same set of tools is reproducible, i.e. the output is always
0007 exactly the same. This makes it possible to verify that the build
0008 infrastructure for a binary distribution or embedded system has not
0009 been subverted. This can also make it easier to verify that a source
0010 or tool change does not make any difference to the resulting binaries.
0011
0012 The `Reproducible Builds project`_ has more information about this
0013 general topic. This document covers the various reasons why building
0014 the kernel may be unreproducible, and how to avoid them.
0015
0016 Timestamps
0017 ----------
0018
0019 The kernel embeds timestamps in three places:
0020
0021 * The version string exposed by ``uname()`` and included in
0022 ``/proc/version``
0023
0024 * File timestamps in the embedded initramfs
0025
0026 * If enabled via ``CONFIG_IKHEADERS``, file timestamps of kernel
0027 headers embedded in the kernel or respective module,
0028 exposed via ``/sys/kernel/kheaders.tar.xz``
0029
0030 By default the timestamp is the current time and in the case of
0031 ``kheaders`` the various files' modification times. This must
0032 be overridden using the `KBUILD_BUILD_TIMESTAMP`_ variable.
0033 If you are building from a git commit, you could use its commit date.
0034
0035 The kernel does *not* use the ``__DATE__`` and ``__TIME__`` macros,
0036 and enables warnings if they are used. If you incorporate external
0037 code that does use these, you must override the timestamp they
0038 correspond to by setting the `SOURCE_DATE_EPOCH`_ environment
0039 variable.
0040
0041 User, host
0042 ----------
0043
0044 The kernel embeds the building user and host names in
0045 ``/proc/version``. These must be overridden using the
0046 `KBUILD_BUILD_USER and KBUILD_BUILD_HOST`_ variables. If you are
0047 building from a git commit, you could use its committer address.
0048
0049 Absolute filenames
0050 ------------------
0051
0052 When the kernel is built out-of-tree, debug information may include
0053 absolute filenames for the source files. This must be overridden by
0054 including the ``-fdebug-prefix-map`` option in the `KCFLAGS`_ variable.
0055
0056 Depending on the compiler used, the ``__FILE__`` macro may also expand
0057 to an absolute filename in an out-of-tree build. Kbuild automatically
0058 uses the ``-fmacro-prefix-map`` option to prevent this, if it is
0059 supported.
0060
0061 The Reproducible Builds web site has more information about these
0062 `prefix-map options`_.
0063
0064 Generated files in source packages
0065 ----------------------------------
0066
0067 The build processes for some programs under the ``tools/``
0068 subdirectory do not completely support out-of-tree builds. This may
0069 cause a later source package build using e.g. ``make rpm-pkg`` to
0070 include generated files. You should ensure the source tree is
0071 pristine by running ``make mrproper`` or ``git clean -d -f -x`` before
0072 building a source package.
0073
0074 Module signing
0075 --------------
0076
0077 If you enable ``CONFIG_MODULE_SIG_ALL``, the default behaviour is to
0078 generate a different temporary key for each build, resulting in the
0079 modules being unreproducible. However, including a signing key with
0080 your source would presumably defeat the purpose of signing modules.
0081
0082 One approach to this is to divide up the build process so that the
0083 unreproducible parts can be treated as sources:
0084
0085 1. Generate a persistent signing key. Add the certificate for the key
0086 to the kernel source.
0087
0088 2. Set the ``CONFIG_SYSTEM_TRUSTED_KEYS`` symbol to include the
0089 signing key's certificate, set ``CONFIG_MODULE_SIG_KEY`` to an
0090 empty string, and disable ``CONFIG_MODULE_SIG_ALL``.
0091 Build the kernel and modules.
0092
0093 3. Create detached signatures for the modules, and publish them as
0094 sources.
0095
0096 4. Perform a second build that attaches the module signatures. It
0097 can either rebuild the modules or use the output of step 2.
0098
0099 Structure randomisation
0100 -----------------------
0101
0102 If you enable ``CONFIG_RANDSTRUCT``, you will need to pre-generate
0103 the random seed in ``scripts/basic/randstruct.seed`` so the same
0104 value is used by each build. See ``scripts/gen-randstruct-seed.sh``
0105 for details.
0106
0107 Debug info conflicts
0108 --------------------
0109
0110 This is not a problem of unreproducibility, but of generated files
0111 being *too* reproducible.
0112
0113 Once you set all the necessary variables for a reproducible build, a
0114 vDSO's debug information may be identical even for different kernel
0115 versions. This can result in file conflicts between debug information
0116 packages for the different kernel versions.
0117
0118 To avoid this, you can make the vDSO different for different
0119 kernel versions by including an arbitrary string of "salt" in it.
0120 This is specified by the Kconfig symbol ``CONFIG_BUILD_SALT``.
0121
0122 .. _KBUILD_BUILD_TIMESTAMP: kbuild.html#kbuild-build-timestamp
0123 .. _KBUILD_BUILD_USER and KBUILD_BUILD_HOST: kbuild.html#kbuild-build-user-kbuild-build-host
0124 .. _KCFLAGS: kbuild.html#kcflags
0125 .. _prefix-map options: https://reproducible-builds.org/docs/build-path/
0126 .. _Reproducible Builds project: https://reproducible-builds.org/
0127 .. _SOURCE_DATE_EPOCH: https://reproducible-builds.org/docs/source-date-epoch/
