// -*- 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+