diff mbox series

[15/15] docs/manual: add a section about SELinux

Message ID 20200731101040.1723047-16-antoine.tenart@bootlin.com
State New
Headers show
Series Improve SELinux support | expand

Commit Message

Antoine Tenart July 31, 2020, 10:10 a.m. UTC
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>
---
 docs/manual/manual.txt          |  2 +
 docs/manual/selinux-support.txt | 66 +++++++++++++++++++++++++++++++++
 2 files changed, 68 insertions(+)
 create mode 100644 docs/manual/selinux-support.txt

Comments

Matthew Weber July 31, 2020, 12:15 p.m. UTC | #1
Antoine,


On Fri, Jul 31, 2020 at 5:16 AM Antoine Tenart
<antoine.tenart@bootlin.com> wrote:
>
> 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>
> ---
>  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.

It may be worth also mentioning that the kernel has configuration
options that play into if the modes are respected.  For example the
kernel could have bootargs set, development mode or policy disabled.
Maybe just adding a reference to the kernel.org kconfig would be
enough (https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/security/selinux/Kconfig)?

> +
> +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...).
> +

It looks like Buildroot via libselinux pkg is setting at least the
following so the user won't have to be concerned with their kernel
support.  Unsure how to tie this into the documentation as the user
won't have to enable more then the filesystem xattrs.  Maybe xattrs
would make sense to globally turn on as well?

define LIBSELINUX_LINUX_CONFIG_FIXUPS
        $(call KCONFIG_ENABLE_OPT,CONFIG_AUDIT)
        $(call KCONFIG_ENABLE_OPT,CONFIG_DEFAULT_SECURITY_SELINUX)
        $(call KCONFIG_ENABLE_OPT,CONFIG_INET)
        $(call KCONFIG_ENABLE_OPT,CONFIG_NET)
        $(call KCONFIG_ENABLE_OPT,CONFIG_SECURITY)
        $(call KCONFIG_ENABLE_OPT,CONFIG_SECURITY_NETWORK)
        $(call KCONFIG_ENABLE_OPT,CONFIG_SECURITY_SELINUX)
endef


Regards,
Matt
Antoine Tenart July 31, 2020, 12:52 p.m. UTC | #2
Hello Matthew,

Quoting Matthew Weber (2020-07-31 14:15:50)
> On Fri, Jul 31, 2020 at 5:16 AM Antoine Tenart
> <antoine.tenart@bootlin.com> wrote:
> > +
> > +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.
> 
> It may be worth also mentioning that the kernel has configuration
> options that play into if the modes are respected.  For example the
> kernel could have bootargs set, development mode or policy disabled.
> Maybe just adding a reference to the kernel.org kconfig would be
> enough (https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/tree/security/selinux/Kconfig)?

I think we could mention other Kconfig options are available in the
kernel and may have an impact on the SELinux policy behaviour. There's a
part about the kernel configuration below, I'll add it there.

> > +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...).
> > +
> 
> It looks like Buildroot via libselinux pkg is setting at least the
> following so the user won't have to be concerned with their kernel
> support.

Right. I'll keep this part, but say the configuration should be
magically fixed by libselinux.

> Unsure how to tie this into the documentation as the user won't have
> to enable more then the filesystem xattrs.  Maybe xattrs would make
> sense to globally turn on as well?

That should be possible, I don't know to what extend do we want to fix
the kernel configuration. As other SELinux Kconfig options are already
turned on by libselinux, I'd say that could make sense.

Thanks!
Antoine
Thomas Petazzoni July 31, 2020, 1:15 p.m. UTC | #3
On Fri, 31 Jul 2020 14:52:14 +0200
Antoine Tenart <antoine.tenart@bootlin.com> wrote:

> > Unsure how to tie this into the documentation as the user won't have
> > to enable more then the filesystem xattrs.  Maybe xattrs would make
> > sense to globally turn on as well?  
> 
> That should be possible, I don't know to what extend do we want to fix
> the kernel configuration. As other SELinux Kconfig options are already
> turned on by libselinux, I'd say that could make sense.

The problem with xattr is that it is typically a per-filesystem option:

./fs/jffs2/Kconfig:config JFFS2_FS_XATTR
./fs/cifs/Kconfig:config CIFS_XATTR
./fs/f2fs/Kconfig:config F2FS_FS_XATTR
./fs/Kconfig:config TMPFS_XATTR
./fs/reiserfs/Kconfig:config REISERFS_FS_XATTR
./fs/erofs/Kconfig:config EROFS_FS_XATTR
./fs/ext2/Kconfig:config EXT2_FS_XATTR
./fs/squashfs/Kconfig:config SQUASHFS_XATTR
./fs/ubifs/Kconfig:config UBIFS_FS_XATTR

Which one do we enable ? All of them, and if the corresponding
filesystem is not enabled, the option will be re-disabled ? That's a
possible option, I'm not sure it's really nice but it should work.

Thomas
Matthew Weber July 31, 2020, 1:19 p.m. UTC | #4
Thomas,

On Fri, Jul 31, 2020 at 8:16 AM Thomas Petazzoni
<thomas.petazzoni@bootlin.com> wrote:
>
> On Fri, 31 Jul 2020 14:52:14 +0200
> Antoine Tenart <antoine.tenart@bootlin.com> wrote:
>
> > > Unsure how to tie this into the documentation as the user won't have
> > > to enable more then the filesystem xattrs.  Maybe xattrs would make
> > > sense to globally turn on as well?
> >
> > That should be possible, I don't know to what extend do we want to fix
> > the kernel configuration. As other SELinux Kconfig options are already
> > turned on by libselinux, I'd say that could make sense.
>
> The problem with xattr is that it is typically a per-filesystem option:
>
> ./fs/jffs2/Kconfig:config JFFS2_FS_XATTR
> ./fs/cifs/Kconfig:config CIFS_XATTR
> ./fs/f2fs/Kconfig:config F2FS_FS_XATTR
> ./fs/Kconfig:config TMPFS_XATTR
> ./fs/reiserfs/Kconfig:config REISERFS_FS_XATTR
> ./fs/erofs/Kconfig:config EROFS_FS_XATTR
> ./fs/ext2/Kconfig:config EXT2_FS_XATTR
> ./fs/squashfs/Kconfig:config SQUASHFS_XATTR
> ./fs/ubifs/Kconfig:config UBIFS_FS_XATTR
>
> Which one do we enable ? All of them, and if the corresponding
> filesystem is not enabled, the option will be re-disabled ? That's a
> possible option, I'm not sure it's really nice but it should work.
>

Agree. not ideal.  But it does create a bug, (funny timing) we
actually just had a review come through internally where the developer
missed enabling JFFS2_FS_XATTR and it resulted in some unnecessary
churn.

Matt
Antoine Tenart July 31, 2020, 1:22 p.m. UTC | #5
Hi Thomas,

Quoting Thomas Petazzoni (2020-07-31 15:15:57)
> On Fri, 31 Jul 2020 14:52:14 +0200
> Antoine Tenart <antoine.tenart@bootlin.com> wrote:
> 
> > > Unsure how to tie this into the documentation as the user won't have
> > > to enable more then the filesystem xattrs.  Maybe xattrs would make
> > > sense to globally turn on as well?  
> > 
> > That should be possible, I don't know to what extend do we want to fix
> > the kernel configuration. As other SELinux Kconfig options are already
> > turned on by libselinux, I'd say that could make sense.
> 
> The problem with xattr is that it is typically a per-filesystem option:
> 
> ./fs/jffs2/Kconfig:config JFFS2_FS_XATTR
> ./fs/cifs/Kconfig:config CIFS_XATTR
> ./fs/f2fs/Kconfig:config F2FS_FS_XATTR
> ./fs/Kconfig:config TMPFS_XATTR
> ./fs/reiserfs/Kconfig:config REISERFS_FS_XATTR
> ./fs/erofs/Kconfig:config EROFS_FS_XATTR
> ./fs/ext2/Kconfig:config EXT2_FS_XATTR
> ./fs/squashfs/Kconfig:config SQUASHFS_XATTR
> ./fs/ubifs/Kconfig:config UBIFS_FS_XATTR
> 
> Which one do we enable ? All of them, and if the corresponding
> filesystem is not enabled, the option will be re-disabled ? That's a
> possible option, I'm not sure it's really nice but it should work.

If we do enable xattr support, that's what I had in mind. I agree it's
not a perfect solution.

Thanks!
Antoine
diff mbox series

Patch

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