Update CLIP OS kernel security documentation
[kconfig-hardened-check.git] / config_files / distros / clipos_kernel_doc.txt
index 7c0a2db4ceb325b33b325fb9e5dce34476f5dd67..f5fc0906d41989506a3b1acdb03e3fa6a60511e5 100644 (file)
@@ -225,15 +225,13 @@ Processor type and features
    required.
 
 .. describe:: CONFIG_LEGACY_VSYSCALL_NONE=y
+              CONFIG_LEGACY_VSYSCALL_EMULATE=n
+              CONFIG_LEGACY_VSYSCALL_XONLY=n
+              CONFIG_X86_VSYSCALL_EMULATION=n
 
    The vsyscall table is not required anymore by libc and is a fixed-position
    potential source of ROP gadgets.
 
-.. describe:: CONFIG_X86_VSYSCALL_EMULATE=n
-              CONFIG_LEGACY_VSYSCALL_XONLY=n
-
-   See above.
-
 .. describe:: CONFIG_MICROCODE=y
 
    Needed to benefit from microcode updates and thus security fixes (e.g.,
@@ -285,9 +283,12 @@ Processor type and features
 
 .. describe:: CONFIG_X86_INTEL_MPX=n
 
-   Intel Memory Protection Extensions add hardware assistance to memory
-   protection. Compiler support is required but is deprecated in GCC 8 and will
-   probably be dropped in GCC 9.
+   Intel Memory Protection Extensions (MPX) add hardware assistance to memory
+   protection. Compiler support is required but was deprecated in GCC 8 and
+   removed from GCC 9. Moreover, MPX kernel support is `being dropped
+   <MPX_dropped_>`_.
+
+   .. _MPX_dropped: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=f240652b6032b48ad7fa35c5e701cc4c8d697c0b
 
 .. describe:: CONFIG_X86_INTEL_MEMORY_PROTECTION_KEYS=n
 
@@ -448,12 +449,19 @@ Device Drivers
    could increase the kernel attack surface.
 
 .. describe:: CONFIG_RANDOM_TRUST_CPU=n
+              CONFIG_RANDOM_TRUST_BOOLOADER=n
+
+   Do not **credit** entropy generated by the CPU manufacturer's HWRNG nor
+   provided by the booloader, and included in Linux's entropy pool. Fast and
+   robust initialization of Linux's CSPRNG is instead achieved thanks to the
+   TPM's HWRNG (see documentation of ``CONFIG_HW_RANDOM_TPM`` and the
+   ``rng_core.default_quality`` command line parameter).
+
+.. describe:: CONFIG_STAGING=n
 
-   Do not **credit** entropy generated by the CPU manufacturer's HWRNG and
-   included in Linux's entropy pool. Fast and robust initialization of Linux's
-   CSPRNG is instead achieved thanks to the TPM's HWRNG (see documentation of
-   ``CONFIG_HW_RANDOM_TPM`` and the ``rng_core.default_quality`` command line
-   parameter).
+   *Staging* drivers are typically of lower quality and under heavy
+   development. They are thus more likely to contain bugs, including security
+   vulnerabilities, and should be avoided.
 
 The IOMMU allows for protecting the system's main memory from arbitrary
 accesses from devices (e.g., DMA attacks). Note that this is related to
@@ -611,6 +619,20 @@ Security
 
    For now, but will eventually be ``n``.
 
+.. describe:: CONFIG_SECURITY_LOCKDOWN_LSM=y
+              CONFIG_SECURITY_LOCKDOWN_LSM_EARLY=y
+              CONFIG_LOCK_DOWN_KERNEL_FORCE_CONFIDENTIALITY=y
+
+   Basically, the *lockdown* LSM tries to strengthen the boundary between the
+   superuser and the kernel. The *integrity* mode thus restricts access to
+   features that would allow userland to modify the running kernel, and the
+   *confidentiality* mode extends these restrictions to features that would
+   allow userland to extract confidential information held inside the kernel.
+   Note that a significant portion of such features is already disabled in the
+   CLIP OS kernel due to our custom configuration. The *lockdown* functionality
+   is important for CLIP OS as we want to prevent an attacker, be he highly
+   privileged, from persisting on a compromised machine.
+
 .. ---
 
 .. describe:: CONFIG_LSM="yama"
@@ -680,19 +702,6 @@ while but eventually `dropped it
 
 .. ---
 
-We incorporated most of the *Lockdown* patch series into the CLIP OS kernel,
-though it may be merged into the mainline kernel in the near future.
-Basically, *Lockdown* tries to disable many mechanisms that could allow the
-superuser to eventually run untrusted code in kernel mode (note that a
-significant portion of them are already disabled in the CLIP OS kernel due to
-our custom configuration). This is an interesting work for CLIP OS as we want
-to avoid persistence on a compromised machine even in the case of an
-already-root attacker. Among the several configuration options brought by
-*Lockdown*, we enable the following ones:
-
-  .. describe:: CONFIG_LOCK_DOWN_KERNEL=y
-                CONFIG_LOCK_DOWN_MANDATORY=y
-
 
 Compilation
 -----------
@@ -746,13 +755,16 @@ read/write access to:
   .. describe:: fs.protected_symlinks = 1
                 fs.protected_hardlinks = 1
 
-In addition, the following other two sysctls impose restrictions on the
-opening of FIFOs and regular files in order to make similar spoofing attacks
-harder:
+In addition, the following other two sysctls impose restrictions on the opening
+of FIFOs and regular files in order to make similar spoofing attacks harder
+(note however that `these restrictions currently do not apply to networked
+filesystems, among others <sysctl_protected_limitations_>`_):
 
   .. describe:: fs.protected_fifos = 2
                 fs.protected_regular = 2
 
+.. _sysctl_protected_limitations: https://www.openwall.com/lists/oss-security/2020/01/28/2
+
 We do not simply disable the BPF Just in Time compiler as CLIP OS plans on
 using it:
 
@@ -921,4 +933,3 @@ Also, note that:
    This item is provided by the ``linux-hardened`` patches.
 
 .. vim: set tw=79 ts=2 sts=2 sw=2 et:
-