From patchwork Fri Jul 31 10:10:40 2020 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Antoine Tenart X-Patchwork-Id: 1339380 Return-Path: X-Original-To: incoming-buildroot@patchwork.ozlabs.org Delivered-To: patchwork-incoming-buildroot@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=busybox.net (client-ip=140.211.166.138; helo=whitealder.osuosl.org; envelope-from=buildroot-bounces@busybox.net; receiver=) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=bootlin.com Received: from whitealder.osuosl.org (smtp1.osuosl.org [140.211.166.138]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4BJ3812lXNz9sRK for ; Fri, 31 Jul 2020 20:15:45 +1000 (AEST) Received: from localhost (localhost [127.0.0.1]) by whitealder.osuosl.org (Postfix) with ESMTP id C36B78863B; Fri, 31 Jul 2020 10:15:43 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from whitealder.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id 9aKYRRFVTkcJ; Fri, 31 Jul 2020 10:15:41 +0000 (UTC) Received: from ash.osuosl.org (ash.osuosl.org [140.211.166.34]) by whitealder.osuosl.org (Postfix) with ESMTP id 8D545885E8; Fri, 31 Jul 2020 10:15:41 +0000 (UTC) X-Original-To: buildroot@lists.busybox.net Delivered-To: buildroot@osuosl.org Received: from fraxinus.osuosl.org (smtp4.osuosl.org [140.211.166.137]) by ash.osuosl.org (Postfix) with ESMTP id 9BEE51BF2A4 for ; Fri, 31 Jul 2020 10:15:29 +0000 (UTC) Received: from localhost (localhost [127.0.0.1]) by fraxinus.osuosl.org (Postfix) with ESMTP id 9555786A33 for ; Fri, 31 Jul 2020 10:15:29 +0000 (UTC) X-Virus-Scanned: amavisd-new at osuosl.org Received: from fraxinus.osuosl.org ([127.0.0.1]) by localhost (.osuosl.org [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id LrDTrp1ghaWB for ; Fri, 31 Jul 2020 10:15:28 +0000 (UTC) X-Greylist: domain auto-whitelisted by SQLgrey-1.7.6 Received: from relay10.mail.gandi.net (relay10.mail.gandi.net [217.70.178.230]) by fraxinus.osuosl.org (Postfix) with ESMTPS id 6630E8696D for ; Fri, 31 Jul 2020 10:15:26 +0000 (UTC) Received: from localhost (lfbn-tou-1-1075-236.w90-76.abo.wanadoo.fr [90.76.143.236]) (Authenticated sender: antoine.tenart@bootlin.com) by relay10.mail.gandi.net (Postfix) with ESMTPSA id 38A89240004; Fri, 31 Jul 2020 10:15:23 +0000 (UTC) From: Antoine Tenart To: buildroot@buildroot.org Date: Fri, 31 Jul 2020 12:10:40 +0200 Message-Id: <20200731101040.1723047-16-antoine.tenart@bootlin.com> X-Mailer: git-send-email 2.26.2 In-Reply-To: <20200731101040.1723047-1-antoine.tenart@bootlin.com> References: <20200731101040.1723047-1-antoine.tenart@bootlin.com> MIME-Version: 1.0 Subject: [Buildroot] [PATCH 15/15] docs/manual: add a section about SELinux X-BeenThere: buildroot@busybox.net X-Mailman-Version: 2.1.29 Precedence: list List-Id: Discussion and development of buildroot List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: matthew.weber@rockwellcollins.com, clshotwe@rockwellcollins.com, thomas.petazzoni@bootlin.com, daniel.riechers@rockwellcollins.com, aduskett@gmail.com Errors-To: buildroot-bounces@busybox.net Sender: "buildroot" 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 --- docs/manual/manual.txt | 2 + docs/manual/selinux-support.txt | 66 +++++++++++++++++++++++++++++++++ 2 files changed, 68 insertions(+) create mode 100644 docs/manual/selinux-support.txt diff --git a/docs/manual/manual.txt b/docs/manual/manual.txt index 48de65ee1033..b5cc044805b1 100644 --- a/docs/manual/manual.txt +++ b/docs/manual/manual.txt @@ -38,6 +38,8 @@ include::common-usage.txt[] include::customize.txt[] +include::selinux-support.txt[] + include::faq-troubleshooting.txt[] include::known-issues.txt[] diff --git a/docs/manual/selinux-support.txt b/docs/manual/selinux-support.txt new file mode 100644 index 000000000000..613b1c8f2275 --- /dev/null +++ b/docs/manual/selinux-support.txt @@ -0,0 +1,66 @@ +// -*- 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 operating: +Enforcing+, +Permissive+ and ++Disabled+. If not +Disabled+, the kernel will apply the policy and +non-authorized actions will be denied in +Enforcing+ mode or logged and reported +in +Permissive+ mode. +Permissive+ mode is often used for troubleshooting +SELinux issues. In Buildroot this is controlled by the ++BR2_PACKAGE_REFPOLICY_POLICY_STATE_*+ configuration options. + +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 needs to be enabled: + +* +BR2_PACKAGE_REFPOLICY+ +* +BR2_PACKAGE_POLICYCOREUTILS+ + +The Linux kernel configuration must also enable +SELinux+ support with ++CONFIG_SECURITY_SELINUX+, +CONFIG_LSM+ (or using the +lsm+ kernel +parameter) and extended attributes in filesystems (+CONFIG_EXT2_FS_XATTR+ for ++ext2+, +CONFIG_SQUASHFS_XATTR+ for +squashfs+, etc...). + +[[selinux-policy-tweaking]] +=== SELinux policy tweaking + +The +SELinux refpolicy+ contains modules that can be enabled or disabled when +being built. In Buildroot the non-base modules are disabled by default and ways +to enable them are provided: + +- Packages can enable a list of +SELinux+ modules within the +refpolicy+ with + the +_SELINUX_MODULES+ variable. +- Packages can provide additional +SELinux+ modules by putting them (.fc, .if + and .te files) in +package//selinux/+. +- Extra +SELinux+ modules can be added if in directories pointed by the + +BR2_REFPOLICY_EXTRA_MODULES_DIRS+ configuration variable. +- Additional modules in the +refpolicy+ can be enabled if listed in the + +BR2_REFPOLICY_EXTRA_MODULES_DEPENDENCIES+ configuration variable. + +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+