Skip to content

Commit 9b11173

Browse files
AashvijShenaicshilwant
AashvijShenai
authored and
cshilwant
committed
docs(linux): Security: Add SELinux documentation
This document details how to build and use SELinux on Yocto and Debian distributions. In order to prepare for the upcoming system security documentation, this guide has been separated into another directory: System_Security. Signed-off-by: Aashvij Shenai <[email protected]>
1 parent e007cb8 commit 9b11173

File tree

5 files changed

+179
-0
lines changed

5 files changed

+179
-0
lines changed

‎configs/AM62AX/AM62AX_linux_toc.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,8 @@ linux/Foundational_Components/Power_Management/pm_wakeup_sources
8888
linux/Foundational_Components/Power_Management/pm_sw_arch
8989
linux/Foundational_Components/Power_Management/pm_debug
9090

91+
linux/Foundational_Components/System_Security/SELinux
92+
9193
linux/Foundational_Components_Kernel_Users_Guide
9294
linux/Foundational_Components_Kernel_LTP-DDT_Validation
9395
linux/Foundational_Components_Kernel_FAQs

‎configs/AM62PX/AM62PX_linux_toc.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -91,6 +91,8 @@ linux/Foundational_Components/Power_Management/pm_wakeup_sources
9191
linux/Foundational_Components/Power_Management/pm_sw_arch
9292
linux/Foundational_Components/Power_Management/pm_debug
9393

94+
linux/Foundational_Components/System_Security/SELinux
95+
9496
linux/Foundational_Components_Kernel_Users_Guide
9597
linux/Foundational_Components_Kernel_LTP-DDT_Validation
9698
linux/Foundational_Components_Kernel_FAQs

‎configs/AM62X/AM62X_linux_toc.txt‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -90,6 +90,8 @@ linux/Foundational_Components/Power_Management/pm_wakeup_sources
9090
linux/Foundational_Components/Power_Management/pm_sw_arch
9191
linux/Foundational_Components/Power_Management/pm_debug
9292

93+
linux/Foundational_Components/System_Security/SELinux
94+
9395
linux/Foundational_Components_PRU_Subsystem
9496
linux/Foundational_Components/PRU-ICSS-Linux-Drivers
9597
linux/Foundational_Components/PRU-ICSS/Linux_Drivers/RemoteProc

‎source/linux/Foundational_Components/System_Security/SELinux.rst‎

Lines changed: 172 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,172 @@
1+
.. _selinux_guide:
2+
3+
####################
4+
SELinux - User Guide
5+
####################
6+
7+
Introduction
8+
************
9+
10+
Security-Enhanced Linux (`SELinux <https://github.com/SELinuxProject>`_) is a project to implement mandatory access control under Linux. It is a set of kernel modifications and user-space tools that provide a mechanism for supporting access control security policies. This project was initially developed by the National Security Agency (NSA), as a reference implementation.
11+
12+
SELinux can run in one of three modes: *enforcing*, *permissive*, or *disabled*.
13+
14+
- Enforcing mode is the recommended mode of operation where SELinux operates normally, enforcing the loaded security policy on the entire system.
15+
- In permissive mode, the system acts as if SELinux is enforcing the loaded security policy, including labeling objects and emitting access denial entries in the logs, but it does not actually deny any operations. While not recommended for production systems, permissive mode can be helpful for SELinux policy development and debugging.
16+
- Disabled mode is strongly discouraged; not only does the system avoid enforcing the SELinux policy, it also avoids labeling any persistent objects such as files, making it difficult to enable SELinux in the future.
17+
18+
.. note::
19+
20+
This guide assumes that the user understands how to build the Linux Kernel and, Yocto or Debian distribution.
21+
22+
Filesystem Setup
23+
****************
24+
25+
Yocto
26+
=====
27+
28+
The following steps describe how to build SELinux user-space tools and configuration on Yocto. Please use :ref:`Processor SDK - Building the SDK with Yocto <building-the-sdk-with-yocto>` as reference.
29+
30+
1. On a fresh build, update the config file to use :file:`configs/arago-scarthgap-selinux-config.txt`. This config includes the opensource `meta-selinux` layer into the build and also adds additional features for the filesystem such as the kernel configs listed below:
31+
32+
.. code-block:: kconfig
33+
34+
CONFIG_AUDIT=y
35+
CONFIG_NETWORK_SECMARK=y
36+
CONFIG_EXT2_FS_SECURITY=y
37+
CONFIG_EXT3_FS_SECURITY=y
38+
CONFIG_EXT4_FS_SECURITY=y
39+
CONFIG_JFS_SECURITY=y
40+
CONFIG_REISERFS_FS_SECURITY=y
41+
CONFIG_JFFS2_FS_SECURITY=y
42+
CONFIG_SECURITY=y
43+
CONFIG_SECURITYFS=y
44+
CONFIG_SECURITY_NETWORK=y
45+
CONFIG_SECURITY_SELINUX=y
46+
CONFIG_SECURITY_SELINUX_BOOTPARAM=y
47+
CONFIG_SECURITY_SELINUX_DEVELOP=y
48+
CONFIG_SECURITY_SELINUX_AVC_STATS=y
49+
CONFIG_AUDIT_GENERIC=y
50+
51+
.. note::
52+
53+
The default policy is targeted. If you want to update it, add the variable ``PREFERRED_PROVIDER_virtual/refpolicy = "refpolicy-<your_choice>"`` to the :file:`local.conf` where ``<your_choice>`` is targeted, mls, mcs.
54+
55+
2. Build the :file:`tisdk-default-image`. Note that other recipes do not package selinux features for now.
56+
57+
.. code-block:: console
58+
59+
$ MACHINE=<machine> bitbake -k tisdk-default-image
60+
61+
3. Your newly built wic image will be generated in ``deploy-ti`` directory. Use :ref:`Linux SD Card Creation Guide <processor-sdk-linux-create-sd-card>` to flash this generated image onto your SD card. By default, SELinux functionality is in the disabled state.
62+
63+
Debian
64+
======
65+
66+
The following steps describe how to install and configure SELinux together with the default policy which enables SELinux for the most important parts of your Debian filesystem. This guide does not describe how to build the filesystem using Debian.
67+
68+
1. The default Debian image provided by TI (:file:`tisdk-debian-trixie-<machine>-<version>.wic.xz`) packages necessary kernel configs to enable SELinux. If you are not using the standard linux kernel provided by debian with an ext2/3/4/xfs/btrfs filesystem, you have to make sure that you are using a SELinux capable kernel and filesystem. For ext2/3/4 there is nothing special to be aware of, but for other filesystems there are still some quirks.
69+
70+
2. On the target machine, get the default policy and the basic set of SELinux utilities by running
71+
72+
.. code-block:: console
73+
74+
$ sudo apt-get install selinux-basics selinux-policy-default auditd
75+
76+
Permissive mode Setup
77+
*********************
78+
79+
It is intended to go into Permissive mode, log the accesses, create the access policy and only then jump to Enforcing mode. Skipping this step would lead to a login failure due to lack of access.
80+
81+
1. Boot the target (in disabled state), Run
82+
83+
.. code-block:: console
84+
85+
root@<machine>:~# fixfiles -F onboot
86+
87+
or
88+
89+
.. code-block:: console
90+
91+
root@<machine>:~# touch /.autorelabel
92+
93+
to ensure that files are relabeled upon next reboot.
94+
95+
.. warning::
96+
97+
When systems run SELinux in permissive mode, users and processes might label various file-system objects incorrectly. File-system objects created while SELinux is disabled are not labeled at all. This behavior causes problems when changing to enforcing mode because SELinux relies on correct labels of file-system objects.
98+
99+
To prevent incorrectly labeled and unlabeled files from causing problems, SELinux automatically relabels file systems when changing from the disabled state to permissive or enforcing mode.
100+
101+
2. Open :file:`/etc/selinux/config` and edit it to ``SELINUX=permissive`` and the policy type you are using.
102+
103+
3. Restart the system. If using U-Boot, add ``security=selinux`` to the boot parameters by stopping at the U-Boot prompt and adding,
104+
105+
.. code-block:: console
106+
107+
=> setenv optargs "security=selinux"
108+
109+
4. If the previous steps were executed correctly, it will take a while to label the filesystems on boot and then it will automatically reboot a second time when that is complete.
110+
111+
.. warning::
112+
113+
If you are using the optargs step, every boot will require you to stop at U-Boot prompt, set optargs and proceed. Not doing so will force SELinux to go back to *disabled* state and you will have to restart the setup.
114+
115+
5. You should now have a working SELinux system, which is in permissive mode. This means that the selinux policy is not enforced, but denials are logged. You can see all would-be denials since the last reboot with a small explanation for each with ``audit2why -al``.
116+
117+
6. Verify your status by running ``sestatus`` or ``getenforce``.
118+
119+
.. code-block:: console
120+
121+
root@<machine>:~# sestatus
122+
SELinux status: enabled
123+
SELinuxfs mount: /sys/fs/selinux
124+
SELinux root directory: /etc/selinux
125+
Loaded policy name: targeted
126+
Current mode: permissive
127+
Mode from config file: permissive
128+
Policy MLS status: disabled
129+
Policy deny_unknown status: allowed
130+
Memory protection checking: actual (secure)
131+
Max kernel policy version: 31
132+
133+
Enforcing mode Setup
134+
********************
135+
136+
This guide serves as a reference implementation and will not be diving into custom policy writing or analysing and fixing SELinux denial details.
137+
138+
1. Assuming you are now in permissive mode, use ``audit2why -al`` to list all the policy violations that occured since booting up.
139+
140+
2. We will be using the ``audit2allow`` tool to generate a local policy and resolve all the violations seen. Run:
141+
142+
.. code-block:: console
143+
144+
root@<machine>:~# audit2allow -a -M myPolicy
145+
146+
Follow the instructions generated by the tool to activate the policy.
147+
148+
.. warning::
149+
150+
It is not recommended to use ``audit2allow`` to generate a local policy module as your first option when you see an SELinux denial. Troubleshooting should start with a check if there is a labeling problem. The second most often case is that you have changed a process configuration, and you forgot to tell SELinux about it
151+
152+
3. Update :file:`/etc/selinux/config` to ``SELINUX=enforcing``, save and reboot.
153+
154+
.. note::
155+
156+
Remember that boot parameter ``security=selinux`` must always be present otherwise you will have to begin anew.
157+
158+
4. Verify your status by using ``sestatus`` or ``getenforce``.
159+
160+
.. code-block:: console
161+
162+
root@<machine>:~# sestatus
163+
SELinux status: enabled
164+
SELinuxfs mount: /sys/fs/selinux
165+
SELinux root directory: /etc/selinux
166+
Loaded policy name: targeted
167+
Current mode: enforcing
168+
Mode from config file: enforcing
169+
Policy MLS status: enabled
170+
Policy deny_unknown status: allowed
171+
Memory protection checking: actual (secure)
172+
Max kernel policy version: 31

‎source/linux/Foundational_Components_Security.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,3 +9,4 @@ Security
99

1010
Foundational_Components_Migration_Guide
1111
Foundational_Components_Secure_Boot
12+
Foundational_Components/System_Security/SELinux

0 commit comments

Comments
 (0)