kumquat-buildroot/docs/manual/selinux-support.txt
Antoine Tenart c38c1cde0d docs/manual: add a section about SELinux
Add documentation about how to use SELinux in Buildroot, and what are
the available mechanisms to extend and customize the SELinux policy.

Signed-off-by: Antoine Tenart <antoine.tenart@bootlin.com>
[Thomas: misc improvements.]
Signed-off-by: Thomas Petazzoni <thomas.petazzoni@bootlin.com>
2020-09-04 14:47:29 +02:00

75 lines
2.9 KiB
Plaintext

// -*- mode:doc; -*-
// vim: set syntax=asciidoc:
[[selinux]]
== Using SELinux in Buildroot
https://selinuxproject.org[SELinux] is a Linux kernel security module
enforcing access control policies. In addition to the traditional file
permissions and access control lists, +SELinux+ allows to write rules
for users or processes to access specific functions of resources
(files, sockets...).
_SELinux_ has three modes of operation:
* _Disabled_: the policy is not applied
* _Permissive_: the policy is applied, and non-authorized actions are
simply logged. This mode is often used for troubleshooting SELinux
issues.
* _Enforcing_: the policy is applied, and non-authorized actions are
denied
In Buildroot the mode of operation is controlled by the
+BR2_PACKAGE_REFPOLICY_POLICY_STATE_*+ configuration options. The
Linux kernel also has various configuration options that affect how
+SELinux+ is enabled (see +security/selinux/Kconfig+ in the Linux
kernel sources).
By default in Buildroot the +SELinux+ policy is provided by the
upstream https://github.com/SELinuxProject/refpolicy[refpolicy]
project, enabled with +BR2_PACKAGE_REFPOLICY+.
[[enabling-selinux]]
=== Enabling SELinux support
To have proper support for +SELinux+ in a Buildroot generated system,
the following configuration options must be enabled:
* +BR2_PACKAGE_LIBSELINUX+
* +BR2_PACKAGE_REFPOLICY+
In addition, your filesystem image format must support extended
attributes.
[[selinux-policy-tweaking]]
=== SELinux policy tweaking
The +SELinux refpolicy+ contains modules that can be enabled or
disabled when being built. Each module provide a number of +SELinux+
rules. In Buildroot the non-base modules are disabled by default and
several ways to enable such modules are provided:
- Packages can enable a list of +SELinux+ modules within the +refpolicy+ using
the +<packagename>_SELINUX_MODULES+ variable.
- Packages can provide additional +SELinux+ modules by putting them (.fc, .if
and .te files) in +package/<packagename>/selinux/+.
- Extra +SELinux+ modules can be added in directories pointed by the
+BR2_REFPOLICY_EXTRA_MODULES_DIRS+ configuration option.
- Additional modules in the +refpolicy+ can be enabled if listed in the
+BR2_REFPOLICY_EXTRA_MODULES_DEPENDENCIES+ configuration option.
Buildroot also allows to completely override the +refpolicy+. This
allows to provide a full custom policy designed specifically for a
given system. When going this way, all of the above mechanisms are
disabled: no extra +SElinux+ module is added to the policy, and all
the available modules within the custom policy are enabled and built
into the final binary policy. The custom policy must be a fork of the
official https://github.com/SELinuxProject/refpolicy[refpolicy].
In order to fully override the +refpolicy+ the following configuration
variables have to be set:
- +BR2_PACKAGE_REFPOLICY_CUSTOM_GIT+
- +BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_URL+
- +BR2_PACKAGE_REFPOLICY_CUSTOM_REPO_VERSION+