Add a new section and supporting examples for embedded systems.
Signed-off-by: Richard Haines <[email protected]>
---
Changes from RFC version: Added comments from Dominick, minor text updates
and rework example Makefiles.
src/embedded_systems.md | 546 ++++++++++++++++++
src/implementing_seaware_apps.md | 2 +-
.../embedded-policy/android-policy/README.md | 34 ++
.../android-policy/android-10/Makefile | 42 ++
.../android-policy/android-4/Makefile | 31 +
.../android-policy/brillo-device/Makefile | 46 ++
.../android-policy/brillo/Makefile | 38 ++
.../reference-policy/README.md | 6 +
.../reference-policy/build.conf | 84 +++
.../reference-policy/modules.conf | 236 ++++++++
src/seandroid.md | 12 +-
src/section_list.txt | 1 +
src/toc.md | 1 +
13 files changed, 1074 insertions(+), 5 deletions(-)
create mode 100644 src/embedded_systems.md
create mode 100644 src/notebook-examples/embedded-policy/android-policy/README.md
create mode 100644 src/notebook-examples/embedded-policy/android-policy/android-10/Makefile
create mode 100644 src/notebook-examples/embedded-policy/android-policy/android-4/Makefile
create mode 100644 src/notebook-examples/embedded-policy/android-policy/brillo-device/Makefile
create mode 100644 src/notebook-examples/embedded-policy/android-policy/brillo/Makefile
create mode 100644 src/notebook-examples/embedded-policy/reference-policy/README.md
create mode 100644 src/notebook-examples/embedded-policy/reference-policy/build.conf
create mode 100644 src/notebook-examples/embedded-policy/reference-policy/modules.conf
diff --git a/src/embedded_systems.md b/src/embedded_systems.md
new file mode 100644
index 0000000..f2c5112
--- /dev/null
+++ b/src/embedded_systems.md
@@ -0,0 +1,546 @@
+# Embedded Systems
+
+- [References](#references)
+- [General Requirements](#general-requirements)
+ - [Project Repositories](#project-repositories)
+ - [Project Requirements](#project-requirements)
+ - [SELinux Libraries and Utilities ](#selinux-libraries-and-utilities)
+ - [Labeling Files](#labeling-files)
+ - [Loading Policy](#loading-policy)
+- [The OpenWrt Project](#the-openwrt-project)
+- [The Android Project](#the-android-project)
+- [Building A Small Monolithic Reference Policy](#building-a-small-monolithic-reference-policy)
+ - [Adding Additional Modules](#adding-additional-modules)
+ - [The Clean-up](#the-clean-up)
+- [Building A Sample Android Policy](#building-a-sample-android-policy)
+
+This section lists some of the general decisions to be taken when implementing
+SELinux on embedded systems, it is by no means complete.
+
+Two embedded SELinux projects are used as examples (OpenWrt and Android) with
+the main emphasis on policy development as this is considered the most difficult
+area.
+The major difference between OpenWrt and Android is that SELinux is not tightly
+integrated in OpenWrt, therefore MAC is addressed in policy rather than also
+adding additional SELinux-awareness to services as in Andriod[^fn_em_1].
+
+An alternative MAC service to consider is [**Smack**](http://www.schaufler-ca.com/)
+(Simplified Mandatory Access Control Kernel) as used in the Samsung
+[**Tizen**](https://www.tizen.org/) and
+[**Automotive Grade Linux**](https://www.automotivelinux.org/) projects. Smack
+can have a smaller, less complex footprint than SELinux.
+
+## References
+
+These papers on embedded systems can be used as references, however they are
+old (2007 - 2015):
+
+- **Security Enhanced (SE) Android: Bringing Flexible MAC to Android** from
+ <http://www.cs.columbia.edu/~lierranli/coms6998-7Spring2014/papers/SEAndroid-NDSS2013.pdf>
+ describes the initial Android changes.
+- **Reducing Resource Consumption of SELinux for Embedded Systems with Contributions to Open-Source Ecosystems**
+ from <https://www.jstage.jst.go.jp/article/ipsjjip/23/5/23_664/_article>
+ describes a scenario where *libselinux* was modified and *libsepol* removed
+ for their embedded system (however no links to their final modified code,
+ although there are many threads on the <https://lore.kernel.org/selinux/>
+ list discussing these changes). It should be noted that these libraries have
+ changed since the original article, therefore it should be used as a
+ reference for ideas only. They also used a now obsolete policy editor
+ [***seedit***](http://seedit.sourceforge.net/) to modify Reference Policies.
+- **Using SELinux security enforcement in Linux-based embedded devices** from
+ <https://eudl.eu/doi/10.4108/icst.mobilware2008.2927> describes enabling
+ SELinux on a Nokia 770 Internet Tablet.
+- **Filesystem considerations for embedded devices** from
+ <https://events.static.linuxfound.org/sites/events/files/slides/fs-for-embedded-full_0.pdf>
+ discusses various embedded filesystems performance and reliability.
+
+## General Requirements
+
+**Note 1** - This section discusses the Reference Policy 'Monolithic' and
+'Modular' policy builds, however this can be confusing, so to clarify:
+
+- The Reference Policy builds both 'Monolithic' and 'Modular' policy using
+ policy modules defined in a *modules.conf* file.
+- The 'Monolithic' build process builds the final policy using
+ ***checkpolicy**(8)* and therefore does NOT make use of the
+ ***semanage**(8)* services to modify policy during runtime.
+- The 'Modular' build process builds the final policy using
+ ***semodule**(8)* and therefore CAN make use of the
+ ***semanage**(8)* services to modify policy during runtime. This requires
+ additional resources as it makes use of the 'policy store[^fn_em_2]' as
+ described in the [**SELinux Configuration Files - The Policy Store**](configuration_files.md#the-policy-store)
+ and [**Policy Store Configuration Files**](policy_store_config_files.md#policy-store-configuration-files)
+ sections.
+ To be clear, it is possible to build a 'Modular' policy on the host system,
+ then install the resulting
+ [**Policy Configuration Files**](policy_config_files.md#policy-configuration-files)
+ onto the target system (i.e. no 'policy store' on the target system).
+- Also note that the Reference Policy 'Monolithic' and 'Modular' builds do not
+ build the exact same list of policy configuration files.
+
+**Note 2** - If the requirement is to build the policy in CIL, it is possible
+to emulate the above by:
+
+- Building policy using ***secilc**(8)* will build a 'Monolithic' policy.
+- Building policy using ***semodule**(8)* will build a 'Modular' policy.
+ This can then make use of the ***semanage**(8)* services to modify policy
+ during runtime as it makes use of the 'policy store[^fn_em_3]'.
+- A useful feature of CIL is that statements can be defined to generate the
+ ***file_contexts**(5)* entries in a consistent manner.
+
+**Note 3** - Is there a requirement to build/rebuild policy on the target, if
+so does it also need to be managed during runtime:
+
+- If build/rebuild policy on the target with NO semanage support, then only
+ ***checkpolicy**(8)* or ***secilc**(8)* will be required on target.
+- If building on the target with runtime changes then ***semodule**(8)* and
+ ***semanage**(8)* are required.
+- If no requirement to build policy on the target, then these are not needed.
+
+**Note 4** - Do any of the target filesystems support extended attributes
+(***xattr**(7)*), if so then ***restorecon**(8)* or ***setfiles**(8)*
+may be required on the target to label files (see the
+[**Labeling Files**](#labeling-files) section).
+
+### Project Repositories
+
+The current SELinux userspace source can be obtained from
+<https://github.com/SELinuxProject/selinux> and the current stable releases
+from <https://github.com/SELinuxProject/selinux/releases>.
+
+The current Reference Policy source can be obtained from
+<https://github.com/SELinuxProject/refpolicy> and the current stable releases
+from <https://github.com/SELinuxProject/refpolicy/releases>.
+
+The current SETools (***apol**(1)* etc.) source can be obtained from
+<https://github.com/SELinuxProject/setools> and the current stable releases
+from <https://github.com/SELinuxProject/setools/releases>.
+
+### Project Requirements
+
+The project requirements will determine the following:
+
+- Kernel Version
+ - The kernel version will determine the maximum policy version supported. The
+ [**Policy Versions**](types_of_policy.md#policy-versions) section details
+ the policy versions, their supported features and SELinux library
+ requirements.
+- Support ***xattr**(7)* Filesystems
+ - If extended attribute filesystems are used then depending on how the target
+ is built/loaded it will require ***restorecon**(8)* or ***setfiles**(8)* to
+ label these file systems. The policy will also require a
+ [*file_contexts*](policy_config_files.md#contextsfilesfile_contexts) that
+ is used to provide the labels.
+- Multi-User
+ - Generally only one user and user role are required, this is the case for
+ OpenWrt and Android. If multi-user then PAM services may be required.
+- Support Tools
+ - These would generally be either [**BusyBox**](https://www.busybox.net/)
+ (OpenWrt) or [**Toybox**](http://landley.net/toybox/) (Android). Both of
+ these can be built with SELinux enabled utilities.
+- Embedded Filesystems
+ - The <https://elinux.org/File_Systems#Embedded_Filesystems> and
+ [**Filesystem considerations for embedded devices**](https://events.static.linuxfound.org/sites/events/files/slides/fs-for-embedded-full_0.pdf)
+ discuss suitable embedded filesystems. If extended attribute
+ (***xattr**(7)*) filesystems are required, then a policy will require a
+ supporting ***file_contexts**(5)* file and the ***restorecon**(8)* utility
+ to label the filesystem.
+- SELinux Policy Support:
+ - Use the Reference Policy, bespoke CIL policy or bespoke policy using
+ ***m4**(1)* macros as used by Android (if starting with a bespoke policy
+ then CIL is recommended). Also need to consider:
+ - If using the Reference Policy on the target device use either:
+ - Monolithic Policy - Use this for minimum resource usage. Also the policy
+ is not so easy to update such items as network port and interface
+ definitions (may need to push a new version to the device).
+ - Modular Policy - Only use this if there is a requirement to modify the
+ device policy during runtime.
+ - Is MCS/MLS Support is required. The
+ [**MLS or MCS Policy**](mls_mcs.md#mls-or-mcs-policy) section gives
+ a brief introduction. The OpenWrt Project does not use MLS/MCS policy,
+ however Android does use MCS for application sandboxing as shown in the
+ [**SE Android - Computing Process Context Examples**](seandroid.md#computing-process-context-examples)
+ section.
+ - Is Conditional Policy (***booleans**(8)*) support required. This allows
+ different policy rules to be enabled/disabled at runtime (Android and
+ OpenWrt do not support Booleans).
+ - SELinux 'user' and user 'roles' (the subject). Generally there would only
+ be one of each of these, for example Android and the OpenWrt CIL policy
+ both use user: *u* role: *r*. Note that the *object_r* role is used to
+ label objects.
+
+### SELinux Libraries and Utilities
+
+The [**Project Repositories**](#project-repositories) section lists the code
+that should be installed on the host build system, not all of these would be
+required on the target system.
+
+A possible minimum list of SELinux items required on the target system are:
+
+- *libselinux* - Provides functions to load policy, label processes and files
+ etc. A list of functions is in
+ [**Appendix B - libselinux API Summary**](libselinux_functions.md#appendix-b---libselinux-api-summary)
+- *libsepol* - Provides services to build/load policy.
+- ***restorecon**(8)* - Label files.
+- The policy plus supporting configuration files.
+
+Whether ***setenforce**(8)* is deployed on the target to set enforcing or
+permissive modes will depend on the overall system requirements.
+
+If ***booleans**(8)* are supported on the target, then ***setsebool**(8)* will
+be required unless ***semanage**(8)* services are installed.
+
+If the target policy is to be:
+
+- Built on the device, then either ***checkpolicy**(8)* or ***secilc**(8)* will
+ be required.
+- Managed on the device during runtime, then ***semanage**(8)*,
+ ***semodule**(8)* and their supporting services will be required.
+
+Depending on the target memory available it would be possible to modify the
+SELinux libraries as there is legacy code that could be removed. Also
+(for example) if the userspace avc (***avc_\***(3)*) services in the
+*libselinux* library are not required these could be removed. It should be
+noted that currently there are no build options to do this.
+
+### Labeling Files
+
+If there is a need to support ***xattr**(7)* filesystems on the target then
+these need to be labeled via the ***file_contexts**(5)* file that would be
+generated as part of the initial policy build.
+
+For example RAM based filesystems will require labeling before use (as Andriod
+does). To achieve this either ***setfiles**(8)* or ***restorecon**(8)* will
+need to be run.
+
+These are based on common source code
+(<https://github.com/SELinuxProject/selinux/tree/master/policycoreutils/setfiles>)
+with the majority of functionality built into *libselinux*, therefore it matters
+little which is used, although ***restorecon**(8)* is probably the best choice
+as it's smaller and does not support checking files against a different policy.
+
+***setfiles**(8)* will label files recursively on directories and is generally
+used by the initial SELinux installation process, whereas ***restorecon**(8)*
+must have the *-r* flag set to label files recursively on directories and is
+generally used to correct/update files on the running system.
+
+### Loading Policy
+
+When the standard *libselinux* and the ***load_policy**(8)* utility are used to
+load policy, it will always be loaded from the
+*/etc/selinux/\<SELINUXTYPE\>/policy* directory, where *\<SELINUXTYPE\>* is
+the entry from the
+[***/etc/selinux/config***](global_config_files.md#etcselinuxconfig) file:
+
+```
+# This file controls the state of SELinux on the system.
+# SELINUX= can take one of these three values:
+# enforcing - SELinux security policy is enforced.
+# permissive - SELinux prints warnings instead of enforcing.
+# disabled - No SELinux policy is loaded.
+SELINUX=enforcing
+# SELINUXTYPE= The <NAME> of the directory where the active policy and its
+# configuration files are located.
+SELINUXTYPE=targeted
+```
+
+The standard Linux SELinux policy load sequence is as follows:
+
+- Obtain policy version supported by the kernel.
+- Obtain minimum policy version supported by *libsepol*.
+- Determine policy load path via */etc/selinux/config* *\<SELINUXTYPE\>* entry.
+- Search for a suitable policy to load by comparing the kernel and *libsepol*
+ versions using the */etc/selinux/\<SELINUXTYPE\>/policy/policy.\<ver\>*
+ file extension.
+- Load and if necessary downgrade the policy. This happens if the policy being
+ loaded has a greater version than the kernel supports. Note that if the
+ policy was built with *--handle-unknown=deny* (*UNK_PERMS* in *build.conf*)
+ and there are unknown classes or permissions, the policy will not be loaded.
+
+The only known deviation from this is the Android project that has its own
+specific method as described in the
+[**SE for Android** - *external/selinux/libselinux*](seandroid.md#externalselinuxlibselinux)
+section. To inspect the code, see the ***selinux_android_load_policy()***
+function in
+<https://android.googlesource.com/platform/external/selinux/+/refs/heads/master/libselinux/src/android/android_platform.c>.
+Basically this maps the policy file to memory, then calls
+***security_load_policy**(3)* to load the policy (as Android does not use the
+version extension or load policy from the */etc/selinux/\<SELINUXTYPE\>/policy*
+directory).
+
+## The OpenWrt Project
+
+The OpenWrt project is a Linux based system targeting embedded devices that can
+be built with either the
+[**Reference Policy**](https://github.com/SELinuxProject/refpolicy) or a
+[**customised CIL policy**](https://git.defensec.nl/?p=selinux-policy.git;a=summary)
+
+The policy to configure is selected from the *menuconfig* options once OpenWrt
+is installed:
+
+```
+make menuconfig
+
+# Select:
+ Global build settings --->
+# Enable SELinux:
+ [*] Enable SELinux
+ default SELinux type (targeted) --->
+# Select either Reference Policy or customised CIL policy (dssp):
+ ( ) targeted
+ (X) dssp
+```
+
+To build and inspect the CIL policy:
+
+```
+git clone https://git.defensec.nl/selinux-policy.git
+cd selinux-policy
+make policy
+```
+
+There should be a binary *policy.\<ver\>* file that can be viewed using tools
+such as ***apol**(1)*. The auto-generated ***file_contexts**(5)* file can be
+viewed with a text editor.
+
+Note that no *policy.conf* is generated when building CIL policy as
+***secilc**(8)* is used. To build a *policy.conf* file for inspection via a
+text editor run:
+
+```
+checkpolicy -bF -o policy.conf policy.31
+```
+
+This work in progress document
+<https://github.com/doverride/openwrt-selinux-policy/blob/master/README.md>
+contains instructions to assemble OpenWrt from modules applicable to a
+particular system and how to build on top of it. Also explained is how to fork
+the policy to form a new base for building a customised target policy.
+
+## The Android Project
+
+This is fully discussed in the
+[**SE for Android**](seandroid.md#security-enhancements-for-android) section
+with a section below that explains
+[**Building A Sample Android Policy**](#building-a-sample-android-policy) to
+examine its construction.
+
+## Building A Small Monolithic Reference Policy
+
+This section describes how a smaller monolithic Reference Policy can be built
+as a starter policy. It supports the minimum of policy modules that can be
+defined in a *modules.conf* file, this file is described in the
+[**Reference Policy Build Options -** *policy/modules.conf*](#reference-policy-build-options---policymodules.conf)
+section.
+
+To start download the Reference Policy source:
+
+```
+git clone https://github.com/SELinuxProject/refpolicy.git
+cd refpolicy
+```
+
+For the initial configuration, either replace the current *build.conf*
+file with the sample
+[***build.conf***](notebook-examples/embedded-policy/reference-policy/build.conf)
+or edit the current *build.conf* file to the requirements (e.g. MONOLITHIC = y)
+
+Install the source policy in the build directory:
+
+```
+make install-src
+cd /etc/selinux/<NAME>/src/policy
+```
+
+The following mandatory *make conf* step will build the initial
+*policy/booleans.conf* and *policy/modules.conf* files.
+
+This process will also build the *policy/modules/kernel/corenetwork.te* and
+*corenetwork.if* files. These would be based on the contents of
+*corenetwork.te.in* and *corenetwork.if.in* configuration files.
+
+For this build only the *policy/modules.conf* will be replaced with the
+sample version.
+
+```
+make conf
+```
+
+Replace the current *policy/modules.conf* with the sample
+[***modules.conf***](notebook-examples/embedded-policy/reference-policy/modules.conf)
+and run:
+
+```
+make install
+```
+
+The binary policy will now be built in the */etc/selinux/\<NAME\>/policy*
+directory. The */etc/selinux/\<NAME\>/src/policy/policy.conf* file contains
+the policy language statements used to generate the binary policy.
+
+The *policy.conf* file can be examined with a text editor and the binary
+*policy.\<ver\>* file can be viewed using tools such as ***apol**(1)*.
+
+### Adding Additional Modules
+
+Note that if the *modules.conf* file is modified to add additional modules,
+*make clean* MUST be run before *make install* or *make load*.
+
+The ease of adding additional modules to the *policy/modules.conf* file depends
+on the modules dependencies, for example to add the *ftp* module:
+
+```
+# Layer: services
+# Module: ftp
+#
+# File transfer protocol service.
+#
+ftp = module
+```
+
+Now run:
+
+```
+make clean
+make install
+```
+
+to build the policy, this will flag a dependency error:
+
+```
+policy/modules/services/ftp.te:488:ERROR 'type ssh_home_t is not within scope'
+```
+
+This shows that the *ftp* module relies on the *ssh* module, therefore need to
+also add:
+
+```
+# Layer: services
+# Module: ssh
+#
+# Secure shell client and server policy.
+#
+ssh = module
+```
+
+Now run:
+
+```
+make clean
+make install
+```
+
+This should build a valid policy. Although note that adding some modules will
+lead to a string of dependent modules.
+
+If a suitable module cannot be found in the *policy/modules* directory, then
+one can be generated and added to the store. To generate policy modules using
+output from the audit log, see ***audit2allow**(1)* (however review any policy
+generated). The
+[**Reference Policy**](reference_policy.md#the-reference-policy) section
+explains the format of these module files.
+
+### The Clean-up
+
+Once a policy is complete it could be cleaned up by removing components
+that are not required for example:
+
+- The *file_contexts* generated will have entries that could be deleted.
+- Unused boleans could be removed.
+- Review Policy Capabilities.
+- Remove unused classes and permissions (*policy/flask/security_classes* and
+ *policy/flask/access_vectors*).
+- There are a number of policy configuration files that can be removed within
+ *etc/selinux/refpolicy* (e.g. *etc/selinux/refpolicy/contexts/x_contexts*).
+
+These will probably amount to small fry, but every little helps!!
+
+## Building A Sample Android Policy
+
+A purpose built embedded policy example is the Android policy that is
+discussed in the
+[**SE for Android**](seandroid.md#security-enhancements-for-android) section.
+This policy has become more complex over time, however they did start with a
+basic policy that can be explored as described below that does not require
+obtaining the full AOSP source and build environment.
+
+[**Android - The SELinux Policy**](seandroid.md#the-selinux-policy) section
+descibes how an Android policy is constructed using ***m4**(1)* macros, *\*.te*
+files etc., similar to the
+[**Reference Policy**](reference_policy.md#the-reference-policy).
+
+To build a sample policy for inspection:
+
+- Obtain a copy of the Android policy built for 4.1, note that only the core
+ policy is built here as Android adds device specific policy modules as per
+ its build configuration (an example build with a device is shown later).
+
+```
+git clone https://android.googlesource.com/platform/external/sepolicy
+cd sepolicy
+git checkout android-4.1.1_r1
+```
+
+- Copy the text below into a
+ [*Makefile*](notebook-examples/embedded-policy/android-policy/android-4/Makefile)
+ installed in the *sepolicy* directory.
+
+```
+build_policy:
+ m4 -D mls_num_sens=1 \
+ -D mls_num_cats=1024 \
+ -s security_classes \
+ initial_sids \
+ access_vectors \
+ global_macros \
+ mls_macros \
+ mls \
+ policy_capabilities \
+ te_macros \
+ attributes \
+ *.te \
+ roles \
+ users \
+ ocontexts > policy.conf
+ checkpolicy -U deny -M -o sepolicy policy.conf
+```
+
+- Run *make* to build the policy. There should be a *policy.conf* file that
+ can be examined with a text editor and a binary *sepolicy* policy
+ file that can be viewed using tools such as ***apol**(1)*.
+ Note the order in which the *policy.conf* file is built as it conforms to
+ the layout described in the
+ [**Kernel Policy Language**](kernel_policy_language.md#policy-source-files)
+ section.
+
+Over time the Android policy locked down more and more processes and then
+became more complex as policy version control was required when upgrading.
+The **Brillo** release was their first IoT release and can be built using the
+instructions in the
+[*brillo/Makefile*](notebook-examples/embedded-policy/android-policy/brillo/Makefile)
+To build a policy containing a device, follow the instructions in the
+[*brillo-device/Makefile*](notebook-examples/embedded-policy/android-policy/brillo-device/Makefile)
+as a device policy must be obtained from the Android repository.
+
+Later Android split policy into private and public segments, they also used
+CIL for some policy components as described in the
+[**Android - The SELinux Policy**](seandroid.md#the-selinux-policy) section.
+The **Android 10** release policy is an example where this split policy is used.
+This can be built using the instructions in the
+[*android-10/Makefile*](notebook-examples/embedded-policy/android-policy/android-10/Makefile).
+
+[^fn_em_1]: An example of this integration is setting a new process context as
+shown in the Zygote code:
+<https://android.googlesource.com/platform/frameworks/base/+/refs/heads/android10-dev/core/jni/com_android_internal_os_Zygote.cpp#1095>.
+The [**SE for Android**](seandroid.md#security-enhancements-for-android) section
+explains SELinux integration within Android AOSP services.
+
+[^fn_em_2]: The 'policy store' holds policy modules in 'policy package' format
+(*\*.pp* files).
+
+[^fn_em_3]: The 'policy store' holds policy modules as compressed CIL text files.
+
+<!-- %CUTHERE% -->
+
+---
+**[[ PREV ]](implementing_seaware_apps.md)** **[[ TOP ]](#)** **[[ NEXT ]](seandroid.md)**
diff --git a/src/implementing_seaware_apps.md b/src/implementing_seaware_apps.md
index ee38258..924df16 100644
--- a/src/implementing_seaware_apps.md
+++ b/src/implementing_seaware_apps.md
@@ -296,4 +296,4 @@ applied to their objects as defined by policy.
<!-- %CUTHERE% -->
---
-**[[ PREV ]](reference_policy.md)** **[[ TOP ]](#)** **[[ NEXT ]](seandroid.md)**
+**[[ PREV ]](reference_policy.md)** **[[ TOP ]](#)** **[[ NEXT ]](embedded_systems.md)**
diff --git a/src/notebook-examples/embedded-policy/android-policy/README.md b/src/notebook-examples/embedded-policy/android-policy/README.md
new file mode 100644
index 0000000..43bc2d8
--- /dev/null
+++ b/src/notebook-examples/embedded-policy/android-policy/README.md
@@ -0,0 +1,34 @@
+# Android Policy
+
+The Android policies defined in these *Makefile* files will allow them to be
+built for inspection without obtaining the full AOSP source and build
+environment.
+
+Note that the core policy is built in most cases as within Android each
+device adds their specific policy modules.
+
+The build process will produce two files:
+
+- *policy.conf* that can be examined with a text editor.
+- *sepolicy* that can be viewed using tools such as ***apol**(1)*.
+
+The ***git**(1)* commands required to obtain the policies are defined in
+each *Makefile*.
+
+- *android-4/Makefile*
+ - The initial Android basic policy.
+
+- *brillo/Makefile*
+ - The Brillo release was their first IoT release.
+
+- *android-10/Makefile*
+ - The Android 10 release split the policy into private and public segments
+ and has started using some CIL modules (although for simplicity they are
+ not built).
+
+## Build policy with a Device
+
+The *brillo-device/Makefile* has instructions to build the Brillo policy with
+a suitable device using the
+*https://android.googlesource.com/platform/external/sepolicy/+archive/refs/heads/brillo-m7-release.tar.gz*
+device policy file.
diff --git a/src/notebook-examples/embedded-policy/android-policy/android-10/Makefile b/src/notebook-examples/embedded-policy/android-policy/android-10/Makefile
new file mode 100644
index 0000000..b13b6ad
--- /dev/null
+++ b/src/notebook-examples/embedded-policy/android-policy/android-10/Makefile
@@ -0,0 +1,42 @@
+#### Build android-10 base policy Makefile ####
+
+# git clone https://android.googlesource.com/platform/system/sepolicy
+# cd sepolicy
+# git checkout android10-dev
+# Copy this Makefile to the sepolicy directory and run 'make' to build the
+# policy files.
+#
+# The policy.conf file can be examined with a text editor and the binary
+# sepolicy file can be viewed using tools such as apol(1).
+#
+# Note this is built with 'target_build_variant=user' and will not have the
+# 'su' permissive domain. Set to 'eng' to add 'su' permissive domain.
+
+build_policy:
+ m4 -D mls_num_sens=1 \
+ -D mls_num_cats=1024 \
+ -D target_build_variant=user \
+ -D target_recovery=false \
+ -s private/security_classes \
+ private/initial_sids \
+ private/access_vectors \
+ public/global_macros \
+ public/neverallow_macros \
+ private/mls_macros \
+ private/mls_decl \
+ private/mls \
+ private/policy_capabilities \
+ public/te_macros \
+ public/attributes \
+ public/ioctl_defines \
+ public/ioctl_macros \
+ public/*.te \
+ private/*.te \
+ private/roles_decl \
+ public/roles \
+ private/users \
+ private/initial_sid_contexts \
+ private/fs_use \
+ private/genfs_contexts \
+ private/port_contexts > policy.conf
+ checkpolicy -U deny -M -o sepolicy policy.conf
diff --git a/src/notebook-examples/embedded-policy/android-policy/android-4/Makefile b/src/notebook-examples/embedded-policy/android-policy/android-4/Makefile
new file mode 100644
index 0000000..40fbccb
--- /dev/null
+++ b/src/notebook-examples/embedded-policy/android-policy/android-4/Makefile
@@ -0,0 +1,31 @@
+#### Build android-4.1.1_r1 base policy Makefile ####
+
+# git clone https://android.googlesource.com/platform/external/sepolicy
+# cd sepolicy
+# git checkout android-4.1.1_r1
+# Copy this Makefile to the sepolicy directory and run 'make' to build the
+# policy files.
+#
+# The policy.conf file can be examined with a text editor and the binary
+# sepolicy file can be viewed using tools such as apol(1).
+
+build_policy:
+ #
+ # Note the order in which the policy.conf file is built:
+ #
+ m4 -D mls_num_sens=1 \
+ -D mls_num_cats=1024 \
+ -s security_classes \
+ initial_sids \
+ access_vectors \
+ global_macros \
+ mls_macros \
+ mls \
+ policy_capabilities \
+ te_macros \
+ attributes \
+ *.te \
+ roles \
+ users \
+ ocontexts > policy.conf
+ checkpolicy -U deny -M -o sepolicy policy.conf
diff --git a/src/notebook-examples/embedded-policy/android-policy/brillo-device/Makefile b/src/notebook-examples/embedded-policy/android-policy/brillo-device/Makefile
new file mode 100644
index 0000000..271cc5c
--- /dev/null
+++ b/src/notebook-examples/embedded-policy/android-policy/brillo-device/Makefile
@@ -0,0 +1,46 @@
+#### Build brillo-m10 + device policy Makefile ####
+
+# git clone https://android.googlesource.com/platform/external/sepolicy
+# cd sepolicy
+# git checkout brillo-m10-release
+# Copy this Makefile to the sepolicy directory and run 'make' to build the
+# policy files.
+#
+# To obtain a buildable device the brillo-m7-dev tar file is downloaded and
+# installed into the sepolicy directory.
+#
+# The policy.conf file can be examined with a text editor and the binary
+# sepolicy file can be viewed using tools such as apol(1).
+
+DEV_DIR := brillo-m7-dev
+
+build_policy:
+ mkdir -p $(DEV_DIR)
+ wget https://android.googlesource.com/device/generic/brillo/+archive/refs/heads/brillo-m7-dev.tar.gz -O - | tar -C $(DEV_DIR) -xz
+ m4 -D mls_num_sens=1 \
+ -D mls_num_cats=1024 \
+ -D target_build_variant=eng \
+ -D target_recovery=false \
+ -s security_classes \
+ $(DEV_DIR)/sepolicy/security_classes \
+ initial_sids \
+ access_vectors \
+ $(DEV_DIR)/sepolicy/access_vectors \
+ global_macros \
+ mls_macros \
+ mls \
+ policy_capabilities \
+ te_macros \
+ $(DEV_DIR)/sepolicy/te_macros \
+ neverallow_macros \
+ attributes \
+ ioctl_macros \
+ *.te \
+ $(DEV_DIR)/sepolicy/*.te \
+ roles \
+ users \
+ initial_sid_contexts \
+ fs_use \
+ genfs_contexts \
+ port_contexts > policy.conf
+ checkpolicy -U deny -M -o sepolicy policy.conf
diff --git a/src/notebook-examples/embedded-policy/android-policy/brillo/Makefile b/src/notebook-examples/embedded-policy/android-policy/brillo/Makefile
new file mode 100644
index 0000000..b715db0
--- /dev/null
+++ b/src/notebook-examples/embedded-policy/android-policy/brillo/Makefile
@@ -0,0 +1,38 @@
+#### Build brillo-m10 base policy Makefile ####
+
+# git clone https://android.googlesource.com/platform/external/sepolicy
+# cd sepolicy
+# git checkout brillo-m10-release
+# Copy this Makefile to the sepolicy directory and run 'make' to build the
+# policy files.
+#
+# The policy.conf file can be examined with a text editor and the binary
+# sepolicy file can be viewed using tools such as apol(1).
+#
+# Note this is built with 'target_build_variant=eng' and will have the 'su'
+# permissive domain. Set to 'user' to remove the 'su' permissive domain.
+
+build_policy:
+ m4 -D mls_num_sens=1 \
+ -D mls_num_cats=1024 \
+ -D target_build_variant=eng \
+ -D target_recovery=false \
+ -s security_classes \
+ initial_sids \
+ access_vectors \
+ global_macros \
+ mls_macros \
+ mls \
+ policy_capabilities \
+ te_macros \
+ neverallow_macros \
+ attributes \
+ ioctl_macros \
+ *.te \
+ roles \
+ users \
+ initial_sid_contexts \
+ fs_use \
+ genfs_contexts \
+ port_contexts > policy.conf
+ checkpolicy -U deny -M -o sepolicy policy.conf
diff --git a/src/notebook-examples/embedded-policy/reference-policy/README.md b/src/notebook-examples/embedded-policy/reference-policy/README.md
new file mode 100644
index 0000000..6d78a58
--- /dev/null
+++ b/src/notebook-examples/embedded-policy/reference-policy/README.md
@@ -0,0 +1,6 @@
+# Building A Small Monolithic Reference Policy
+
+The *modules.conf* file supports the minimum of policy modules that can be
+defined to build a small monolithic policy as described in the
+[Building A Small Monolithic Reference Policy](embedded_systems.md#building-a-small-monolithic-reference-policy)
+section.
diff --git a/src/notebook-examples/embedded-policy/reference-policy/build.conf b/src/notebook-examples/embedded-policy/reference-policy/build.conf
new file mode 100644
index 0000000..f6d0f46
--- /dev/null
+++ b/src/notebook-examples/embedded-policy/reference-policy/build.conf
@@ -0,0 +1,84 @@
+########################################
+#
+# Policy build options
+#
+
+# Policy version
+# By default, checkpolicy will create the highest
+# version policy it supports. Setting this will
+# override the version. This only has an
+# effect for monolithic policies.
+#OUTPUT_POLICY = 18
+
+# Policy Type
+# standard, mls, mcs
+TYPE = standard
+
+# Policy Name
+# If set, this will be used as the policy
+# name. Otherwise the policy type will be
+# used for the name.
+NAME = refpolicy
+
+# Distribution
+# Some distributions have portions of policy
+# for programs or configurations specific to the
+# distribution. Setting this will enable options
+# for the distribution.
+# redhat, gentoo, debian, suse, and rhel4 are current options.
+# Fedora users should enable redhat.
+#DISTRO = redhat
+
+# Unknown Permissions Handling
+# The behavior for handling permissions defined in the
+# kernel but missing from the policy. The permissions
+# can either be allowed, denied, or the policy loading
+# can be rejected.
+# allow, deny, and reject are current options.
+UNK_PERMS = deny
+
+# Direct admin init
+# Setting this will allow sysadm to directly
+# run init scripts, instead of requiring run_init.
+# This is a build option, as role transitions do
+# not work in conditional policy.
+DIRECT_INITRC = n
+
+# Systemd
+# Setting this will configure systemd as the init system.
+SYSTEMD = n
+
+# Build monolithic policy. Putting y here
+# will build a monolithic policy.
+MONOLITHIC = y
+
+# User-based access control (UBAC)
+# Enable UBAC for role separations.
+UBAC = n
+
+# Custom build options. This field enables custom
+# build options. Putting foo here will enable
+# build option blocks named foo. Options should be
+# separated by spaces.
+CUSTOM_BUILDOPT =
+
+# Number of MLS Sensitivities
+# The sensitivities will be s0 to s(MLS_SENS-1).
+# Dominance will be in increasing numerical order
+# with s0 being lowest.
+MLS_SENS = 16
+
+# Number of MLS Categories
+# The categories will be c0 to c(MLS_CATS-1).
+MLS_CATS = 1024
+
+# Number of MCS Categories
+# The categories will be c0 to c(MLS_CATS-1).
+MCS_CATS = 1024
+
+# Set this to y to only display status messages
+# during build.
+QUIET = n
+
+# Set this to treat warnings as errors.
+WERROR = n
diff --git a/src/notebook-examples/embedded-policy/reference-policy/modules.conf b/src/notebook-examples/embedded-policy/reference-policy/modules.conf
new file mode 100644
index 0000000..091a22b
--- /dev/null
+++ b/src/notebook-examples/embedded-policy/reference-policy/modules.conf
@@ -0,0 +1,236 @@
+#
+# This file contains a listing of available modules.
+# To prevent a module from being used in policy
+# creation, set the module name to "off".
+#
+# For monolithic policies, modules set to "base" and "module"
+# will be built into the policy.
+#
+# For modular policies, modules set to "base" will be
+# included in the base module. "module" will be compiled
+# as individual loadable modules.
+#
+
+# Layer: kernel
+# Module: corecommands
+# Required in base
+#
+# Core policy for shells, and generic programs
+# in /bin, /sbin, /usr/bin, and /usr/sbin.
+#
+corecommands = base
+
+# Layer: kernel
+# Module: corenetwork
+# Required in base
+#
+# Policy controlling access to network objects
+#
+corenetwork = base
+
+# Layer: kernel
+# Module: devices
+# Required in base
+#
+# Device nodes and interfaces for many basic system devices.
+#
+devices = base
+
+# Layer: kernel
+# Module: domain
+# Required in base
+#
+# Core policy for domains.
+#
+domain = base
+
+# Layer: kernel
+# Module: files
+# Required in base
+#
+# Basic filesystem types and interfaces.
+#
+files = base
+
+# Layer: kernel
+# Module: filesystem
+# Required in base
+#
+# Policy for filesystems.
+#
+filesystem = base
+
+# Layer: kernel
+# Module: kernel
+# Required in base
+#
+# Policy for kernel threads, proc filesystem,
+# and unlabeled processes and objects.
+#
+kernel = base
+
+# Layer: kernel
+# Module: mcs
+# Required in base
+#
+# Multicategory security policy
+#
+mcs = base
+
+# Layer: kernel
+# Module: mls
+# Required in base
+#
+# Multilevel security policy
+#
+mls = base
+
+# Layer: kernel
+# Module: selinux
+# Required in base
+#
+# Policy for kernel security interface, in particular, selinuxfs.
+#
+selinux = base
+
+# Layer: kernel
+# Module: terminal
+# Required in base
+#
+# Policy for terminals.
+#
+terminal = base
+
+# Layer: kernel
+# Module: ubac
+# Required in base
+#
+# User-based access control policy
+#
+ubac = base
+
+# Layer: kernel
+# Module: storage
+#
+# Policy controlling access to storage devices
+#
+storage = module
+
+# Layer: system
+# Module: application
+#
+# Policy for user executable applications.
+#
+application = module
+
+# Layer: system
+# Module: authlogin
+#
+# Common policy for authentication and user login.
+#
+authlogin = module
+
+# Layer: system
+# Module: clock
+#
+# Policy for reading and setting the hardware clock.
+#
+clock = module
+
+# Layer: system
+# Module: getty
+#
+# Manages physical or virtual terminals.
+#
+getty = module
+
+# Layer: system
+# Module: init
+#
+# System initialization programs (init and init scripts).
+#
+init = module
+
+# Layer: system
+# Module: libraries
+#
+# Policy for system libraries.
+#
+libraries = module
+
+# Layer: system
+# Module: locallogin
+#
+# Policy for local logins.
+#
+locallogin = module
+
+# Layer: system
+# Module: logging
+#
+# Policy for the kernel message logger and system logging daemon.
+#
+logging = module
+
+# Layer: system
+# Module: miscfiles
+#
+# Miscellaneous files.
+#
+miscfiles = module
+
+# Layer: system
+# Module: modutils
+#
+# Policy for kernel module utilities
+#
+modutils = module
+
+# Layer: system
+# Module: mount
+#
+# Policy for mount.
+#
+mount = module
+
+# Layer: system
+# Module: selinuxutil
+#
+# Policy for SELinux policy and userland applications.
+#
+selinuxutil = module
+
+# Layer: system
+# Module: sysnetwork
+#
+# Policy for network configuration: ifconfig and dhcp client.
+#
+sysnetwork = module
+
+# Layer: system
+# Module: udev
+#
+# Policy for udev.
+#
+udev = module
+
+# Layer: system
+# Module: unconfined
+#
+# The unconfined domain.
+#
+unconfined = module
+
+# Layer: system
+# Module: userdomain
+#
+# Policy for user domains
+#
+userdomain = module
+
+# Layer: roles
+# Module: sysadm
+#
+# General system administration role
+#
+sysadm = module
diff --git a/src/seandroid.md b/src/seandroid.md
index 409afe0..dc90513 100644
--- a/src/seandroid.md
+++ b/src/seandroid.md
@@ -76,9 +76,9 @@ idea of the scope.
Provides the SELinux userspace function library that is installed on the
device. It has additional functions to support Android as summarised in
-*external/selinux/README.android*. It is build from a merged upstream version
+*external/selinux/README.android*. It is built from a merged upstream version
(<https://github.com/SELinuxProject/selinux>) with Android specific additions
-such as:
+(<https://android.googlesource.com/platform/external/selinux/>) such as:
***selinux_android_setcontext()***
@@ -160,7 +160,7 @@ There are no specific updates to support Android except an *Android.bp* file.
### ***bootable/recovery***
Changes to manage file labeling on recovery using functions such as
-***selinux_android_file_context_handle()**, ***selabel_lookup**(3)* and
+**selinux_android_file_context_handle()**, ***selabel_lookup**(3)* and
***setfscreatecon**(3)*.
### ***build***
@@ -210,6 +210,10 @@ The Android specific object classes are described in the
[**Android Classes & Permissions**](#android-classes-permissions)
section.
+The [**Embedded Systems - Building A Sample Android Policy**](embedded-systems#building-a-sample-android-policy)
+section explains how to build basic Android policies. These can be explored
+without requiring the full AOSP source and build environment.
+
### ***kernel***
All Android kernels support the Linux Security Module (LSM) and SELinux
@@ -1593,4 +1597,4 @@ USERDEBUG : $DEFAULT_SYSTEM_DEV_CERTIFICATE/testkey.x509.pem
<!-- %CUTHERE% -->
---
-**[[ PREV ]](implementing_seaware_apps.md)** **[[ TOP ]](#)** **[[ NEXT ]](object_classes_permissions.md)**
+**[[ PREV ]](embedded_systems.md)** **[[ TOP ]](#)** **[[ NEXT ]](object_classes_permissions.md)**
diff --git a/src/section_list.txt b/src/section_list.txt
index 340e516..dcca883 100644
--- a/src/section_list.txt
+++ b/src/section_list.txt
@@ -53,6 +53,7 @@ xen_statements.md
modular_policy_statements.md
reference_policy.md
implementing_seaware_apps.md
+embedded_systems.md
seandroid.md
object_classes_permissions.md
libselinux_functions.md
diff --git a/src/toc.md b/src/toc.md
index d915b42..f5778bd 100644
--- a/src/toc.md
+++ b/src/toc.md
@@ -54,6 +54,7 @@
- [Modular Policy Support Statements](modular_policy_statements.md#modular-policy-support-statements)
- [The Reference Policy](reference_policy.md#the-reference-policy)
- [Implementing SELinux-aware Applications](implementing_seaware_apps.md#implementing-selinux-aware-applications)
+- [Embedded Systems](embedded_systems.md#embedded-systems)
- [SE for Android](seandroid.md#security-enhancements-for-android)
- [Appendix A - Object Classes and Permissions](object_classes_permissions.md#appendix-a---object-classes-and-permissions)
- [Appendix B - *libselinux* API Summary](libselinux_functions.md#appendix-b---libselinux-api-summary)
--
2.29.2
Richard Haines <[email protected]> writes:
> Add a new section and supporting examples for embedded systems.
Looks good. Thanks
I will probably submit a patch once this one is committed that expands a
little on the OpenWrt scenario.
>
> Signed-off-by: Richard Haines <[email protected]>
> ---
> Changes from RFC version: Added comments from Dominick, minor text updates
> and rework example Makefiles.
>
> src/embedded_systems.md | 546 ++++++++++++++++++
> src/implementing_seaware_apps.md | 2 +-
> .../embedded-policy/android-policy/README.md | 34 ++
> .../android-policy/android-10/Makefile | 42 ++
> .../android-policy/android-4/Makefile | 31 +
> .../android-policy/brillo-device/Makefile | 46 ++
> .../android-policy/brillo/Makefile | 38 ++
> .../reference-policy/README.md | 6 +
> .../reference-policy/build.conf | 84 +++
> .../reference-policy/modules.conf | 236 ++++++++
> src/seandroid.md | 12 +-
> src/section_list.txt | 1 +
> src/toc.md | 1 +
> 13 files changed, 1074 insertions(+), 5 deletions(-)
> create mode 100644 src/embedded_systems.md
> create mode 100644 src/notebook-examples/embedded-policy/android-policy/README.md
> create mode 100644 src/notebook-examples/embedded-policy/android-policy/android-10/Makefile
> create mode 100644 src/notebook-examples/embedded-policy/android-policy/android-4/Makefile
> create mode 100644 src/notebook-examples/embedded-policy/android-policy/brillo-device/Makefile
> create mode 100644 src/notebook-examples/embedded-policy/android-policy/brillo/Makefile
> create mode 100644 src/notebook-examples/embedded-policy/reference-policy/README.md
> create mode 100644 src/notebook-examples/embedded-policy/reference-policy/build.conf
> create mode 100644 src/notebook-examples/embedded-policy/reference-policy/modules.conf
>
> diff --git a/src/embedded_systems.md b/src/embedded_systems.md
> new file mode 100644
> index 0000000..f2c5112
> --- /dev/null
> +++ b/src/embedded_systems.md
> @@ -0,0 +1,546 @@
> +# Embedded Systems
> +
> +- [References](#references)
> +- [General Requirements](#general-requirements)
> + - [Project Repositories](#project-repositories)
> + - [Project Requirements](#project-requirements)
> + - [SELinux Libraries and Utilities ](#selinux-libraries-and-utilities)
> + - [Labeling Files](#labeling-files)
> + - [Loading Policy](#loading-policy)
> +- [The OpenWrt Project](#the-openwrt-project)
> +- [The Android Project](#the-android-project)
> +- [Building A Small Monolithic Reference Policy](#building-a-small-monolithic-reference-policy)
> + - [Adding Additional Modules](#adding-additional-modules)
> + - [The Clean-up](#the-clean-up)
> +- [Building A Sample Android Policy](#building-a-sample-android-policy)
> +
> +This section lists some of the general decisions to be taken when implementing
> +SELinux on embedded systems, it is by no means complete.
> +
> +Two embedded SELinux projects are used as examples (OpenWrt and Android) with
> +the main emphasis on policy development as this is considered the most difficult
> +area.
> +The major difference between OpenWrt and Android is that SELinux is not tightly
> +integrated in OpenWrt, therefore MAC is addressed in policy rather than also
> +adding additional SELinux-awareness to services as in Andriod[^fn_em_1].
> +
> +An alternative MAC service to consider is [**Smack**](http://www.schaufler-ca.com/)
> +(Simplified Mandatory Access Control Kernel) as used in the Samsung
> +[**Tizen**](https://www.tizen.org/) and
> +[**Automotive Grade Linux**](https://www.automotivelinux.org/) projects. Smack
> +can have a smaller, less complex footprint than SELinux.
> +
> +## References
> +
> +These papers on embedded systems can be used as references, however they are
> +old (2007 - 2015):
> +
> +- **Security Enhanced (SE) Android: Bringing Flexible MAC to Android** from
> + <http://www.cs.columbia.edu/~lierranli/coms6998-7Spring2014/papers/SEAndroid-NDSS2013.pdf>
> + describes the initial Android changes.
> +- **Reducing Resource Consumption of SELinux for Embedded Systems with Contributions to Open-Source Ecosystems**
> + from <https://www.jstage.jst.go.jp/article/ipsjjip/23/5/23_664/_article>
> + describes a scenario where *libselinux* was modified and *libsepol* removed
> + for their embedded system (however no links to their final modified code,
> + although there are many threads on the <https://lore.kernel.org/selinux/>
> + list discussing these changes). It should be noted that these libraries have
> + changed since the original article, therefore it should be used as a
> + reference for ideas only. They also used a now obsolete policy editor
> + [***seedit***](http://seedit.sourceforge.net/) to modify Reference Policies.
> +- **Using SELinux security enforcement in Linux-based embedded devices** from
> + <https://eudl.eu/doi/10.4108/icst.mobilware2008.2927> describes enabling
> + SELinux on a Nokia 770 Internet Tablet.
> +- **Filesystem considerations for embedded devices** from
> + <https://events.static.linuxfound.org/sites/events/files/slides/fs-for-embedded-full_0.pdf>
> + discusses various embedded filesystems performance and reliability.
> +
> +## General Requirements
> +
> +**Note 1** - This section discusses the Reference Policy 'Monolithic' and
> +'Modular' policy builds, however this can be confusing, so to clarify:
> +
> +- The Reference Policy builds both 'Monolithic' and 'Modular' policy using
> + policy modules defined in a *modules.conf* file.
> +- The 'Monolithic' build process builds the final policy using
> + ***checkpolicy**(8)* and therefore does NOT make use of the
> + ***semanage**(8)* services to modify policy during runtime.
> +- The 'Modular' build process builds the final policy using
> + ***semodule**(8)* and therefore CAN make use of the
> + ***semanage**(8)* services to modify policy during runtime. This requires
> + additional resources as it makes use of the 'policy store[^fn_em_2]' as
> + described in the [**SELinux Configuration Files - The Policy Store**](configuration_files.md#the-policy-store)
> + and [**Policy Store Configuration Files**](policy_store_config_files.md#policy-store-configuration-files)
> + sections.
> + To be clear, it is possible to build a 'Modular' policy on the host system,
> + then install the resulting
> + [**Policy Configuration Files**](policy_config_files.md#policy-configuration-files)
> + onto the target system (i.e. no 'policy store' on the target system).
> +- Also note that the Reference Policy 'Monolithic' and 'Modular' builds do not
> + build the exact same list of policy configuration files.
> +
> +**Note 2** - If the requirement is to build the policy in CIL, it is possible
> +to emulate the above by:
> +
> +- Building policy using ***secilc**(8)* will build a 'Monolithic' policy.
> +- Building policy using ***semodule**(8)* will build a 'Modular' policy.
> + This can then make use of the ***semanage**(8)* services to modify policy
> + during runtime as it makes use of the 'policy store[^fn_em_3]'.
> +- A useful feature of CIL is that statements can be defined to generate the
> + ***file_contexts**(5)* entries in a consistent manner.
> +
> +**Note 3** - Is there a requirement to build/rebuild policy on the target, if
> +so does it also need to be managed during runtime:
> +
> +- If build/rebuild policy on the target with NO semanage support, then only
> + ***checkpolicy**(8)* or ***secilc**(8)* will be required on target.
> +- If building on the target with runtime changes then ***semodule**(8)* and
> + ***semanage**(8)* are required.
> +- If no requirement to build policy on the target, then these are not needed.
> +
> +**Note 4** - Do any of the target filesystems support extended attributes
> +(***xattr**(7)*), if so then ***restorecon**(8)* or ***setfiles**(8)*
> +may be required on the target to label files (see the
> +[**Labeling Files**](#labeling-files) section).
> +
> +### Project Repositories
> +
> +The current SELinux userspace source can be obtained from
> +<https://github.com/SELinuxProject/selinux> and the current stable releases
> +from <https://github.com/SELinuxProject/selinux/releases>.
> +
> +The current Reference Policy source can be obtained from
> +<https://github.com/SELinuxProject/refpolicy> and the current stable releases
> +from <https://github.com/SELinuxProject/refpolicy/releases>.
> +
> +The current SETools (***apol**(1)* etc.) source can be obtained from
> +<https://github.com/SELinuxProject/setools> and the current stable releases
> +from <https://github.com/SELinuxProject/setools/releases>.
> +
> +### Project Requirements
> +
> +The project requirements will determine the following:
> +
> +- Kernel Version
> + - The kernel version will determine the maximum policy version supported. The
> + [**Policy Versions**](types_of_policy.md#policy-versions) section details
> + the policy versions, their supported features and SELinux library
> + requirements.
> +- Support ***xattr**(7)* Filesystems
> + - If extended attribute filesystems are used then depending on how the target
> + is built/loaded it will require ***restorecon**(8)* or ***setfiles**(8)* to
> + label these file systems. The policy will also require a
> + [*file_contexts*](policy_config_files.md#contextsfilesfile_contexts) that
> + is used to provide the labels.
> +- Multi-User
> + - Generally only one user and user role are required, this is the case for
> + OpenWrt and Android. If multi-user then PAM services may be required.
> +- Support Tools
> + - These would generally be either [**BusyBox**](https://www.busybox.net/)
> + (OpenWrt) or [**Toybox**](http://landley.net/toybox/) (Android). Both of
> + these can be built with SELinux enabled utilities.
> +- Embedded Filesystems
> + - The <https://elinux.org/File_Systems#Embedded_Filesystems> and
> + [**Filesystem considerations for embedded devices**](https://events.static.linuxfound.org/sites/events/files/slides/fs-for-embedded-full_0.pdf)
> + discuss suitable embedded filesystems. If extended attribute
> + (***xattr**(7)*) filesystems are required, then a policy will require a
> + supporting ***file_contexts**(5)* file and the ***restorecon**(8)* utility
> + to label the filesystem.
> +- SELinux Policy Support:
> + - Use the Reference Policy, bespoke CIL policy or bespoke policy using
> + ***m4**(1)* macros as used by Android (if starting with a bespoke policy
> + then CIL is recommended). Also need to consider:
> + - If using the Reference Policy on the target device use either:
> + - Monolithic Policy - Use this for minimum resource usage. Also the policy
> + is not so easy to update such items as network port and interface
> + definitions (may need to push a new version to the device).
> + - Modular Policy - Only use this if there is a requirement to modify the
> + device policy during runtime.
> + - Is MCS/MLS Support is required. The
> + [**MLS or MCS Policy**](mls_mcs.md#mls-or-mcs-policy) section gives
> + a brief introduction. The OpenWrt Project does not use MLS/MCS policy,
> + however Android does use MCS for application sandboxing as shown in the
> + [**SE Android - Computing Process Context Examples**](seandroid.md#computing-process-context-examples)
> + section.
> + - Is Conditional Policy (***booleans**(8)*) support required. This allows
> + different policy rules to be enabled/disabled at runtime (Android and
> + OpenWrt do not support Booleans).
> + - SELinux 'user' and user 'roles' (the subject). Generally there would only
> + be one of each of these, for example Android and the OpenWrt CIL policy
> + both use user: *u* role: *r*. Note that the *object_r* role is used to
> + label objects.
> +
> +### SELinux Libraries and Utilities
> +
> +The [**Project Repositories**](#project-repositories) section lists the code
> +that should be installed on the host build system, not all of these would be
> +required on the target system.
> +
> +A possible minimum list of SELinux items required on the target system are:
> +
> +- *libselinux* - Provides functions to load policy, label processes and files
> + etc. A list of functions is in
> + [**Appendix B - libselinux API Summary**](libselinux_functions.md#appendix-b---libselinux-api-summary)
> +- *libsepol* - Provides services to build/load policy.
> +- ***restorecon**(8)* - Label files.
> +- The policy plus supporting configuration files.
> +
> +Whether ***setenforce**(8)* is deployed on the target to set enforcing or
> +permissive modes will depend on the overall system requirements.
> +
> +If ***booleans**(8)* are supported on the target, then ***setsebool**(8)* will
> +be required unless ***semanage**(8)* services are installed.
> +
> +If the target policy is to be:
> +
> +- Built on the device, then either ***checkpolicy**(8)* or ***secilc**(8)* will
> + be required.
> +- Managed on the device during runtime, then ***semanage**(8)*,
> + ***semodule**(8)* and their supporting services will be required.
> +
> +Depending on the target memory available it would be possible to modify the
> +SELinux libraries as there is legacy code that could be removed. Also
> +(for example) if the userspace avc (***avc_\***(3)*) services in the
> +*libselinux* library are not required these could be removed. It should be
> +noted that currently there are no build options to do this.
> +
> +### Labeling Files
> +
> +If there is a need to support ***xattr**(7)* filesystems on the target then
> +these need to be labeled via the ***file_contexts**(5)* file that would be
> +generated as part of the initial policy build.
> +
> +For example RAM based filesystems will require labeling before use (as Andriod
> +does). To achieve this either ***setfiles**(8)* or ***restorecon**(8)* will
> +need to be run.
> +
> +These are based on common source code
> +(<https://github.com/SELinuxProject/selinux/tree/master/policycoreutils/setfiles>)
> +with the majority of functionality built into *libselinux*, therefore it matters
> +little which is used, although ***restorecon**(8)* is probably the best choice
> +as it's smaller and does not support checking files against a different policy.
> +
> +***setfiles**(8)* will label files recursively on directories and is generally
> +used by the initial SELinux installation process, whereas ***restorecon**(8)*
> +must have the *-r* flag set to label files recursively on directories and is
> +generally used to correct/update files on the running system.
> +
> +### Loading Policy
> +
> +When the standard *libselinux* and the ***load_policy**(8)* utility are used to
> +load policy, it will always be loaded from the
> +*/etc/selinux/\<SELINUXTYPE\>/policy* directory, where *\<SELINUXTYPE\>* is
> +the entry from the
> +[***/etc/selinux/config***](global_config_files.md#etcselinuxconfig) file:
> +
> +```
> +# This file controls the state of SELinux on the system.
> +# SELINUX= can take one of these three values:
> +# enforcing - SELinux security policy is enforced.
> +# permissive - SELinux prints warnings instead of enforcing.
> +# disabled - No SELinux policy is loaded.
> +SELINUX=enforcing
> +# SELINUXTYPE= The <NAME> of the directory where the active policy and its
> +# configuration files are located.
> +SELINUXTYPE=targeted
> +```
> +
> +The standard Linux SELinux policy load sequence is as follows:
> +
> +- Obtain policy version supported by the kernel.
> +- Obtain minimum policy version supported by *libsepol*.
> +- Determine policy load path via */etc/selinux/config* *\<SELINUXTYPE\>* entry.
> +- Search for a suitable policy to load by comparing the kernel and *libsepol*
> + versions using the */etc/selinux/\<SELINUXTYPE\>/policy/policy.\<ver\>*
> + file extension.
> +- Load and if necessary downgrade the policy. This happens if the policy being
> + loaded has a greater version than the kernel supports. Note that if the
> + policy was built with *--handle-unknown=deny* (*UNK_PERMS* in *build.conf*)
> + and there are unknown classes or permissions, the policy will not be loaded.
> +
> +The only known deviation from this is the Android project that has its own
> +specific method as described in the
> +[**SE for Android** - *external/selinux/libselinux*](seandroid.md#externalselinuxlibselinux)
> +section. To inspect the code, see the ***selinux_android_load_policy()***
> +function in
> +<https://android.googlesource.com/platform/external/selinux/+/refs/heads/master/libselinux/src/android/android_platform.c>.
> +Basically this maps the policy file to memory, then calls
> +***security_load_policy**(3)* to load the policy (as Android does not use the
> +version extension or load policy from the */etc/selinux/\<SELINUXTYPE\>/policy*
> +directory).
> +
> +## The OpenWrt Project
> +
> +The OpenWrt project is a Linux based system targeting embedded devices that can
> +be built with either the
> +[**Reference Policy**](https://github.com/SELinuxProject/refpolicy) or a
> +[**customised CIL policy**](https://git.defensec.nl/?p=selinux-policy.git;a=summary)
> +
> +The policy to configure is selected from the *menuconfig* options once OpenWrt
> +is installed:
> +
> +```
> +make menuconfig
> +
> +# Select:
> + Global build settings --->
> +# Enable SELinux:
> + [*] Enable SELinux
> + default SELinux type (targeted) --->
> +# Select either Reference Policy or customised CIL policy (dssp):
> + ( ) targeted
> + (X) dssp
> +```
> +
> +To build and inspect the CIL policy:
> +
> +```
> +git clone https://git.defensec.nl/selinux-policy.git
> +cd selinux-policy
> +make policy
> +```
> +
> +There should be a binary *policy.\<ver\>* file that can be viewed using tools
> +such as ***apol**(1)*. The auto-generated ***file_contexts**(5)* file can be
> +viewed with a text editor.
> +
> +Note that no *policy.conf* is generated when building CIL policy as
> +***secilc**(8)* is used. To build a *policy.conf* file for inspection via a
> +text editor run:
> +
> +```
> +checkpolicy -bF -o policy.conf policy.31
> +```
> +
> +This work in progress document
> +<https://github.com/doverride/openwrt-selinux-policy/blob/master/README.md>
> +contains instructions to assemble OpenWrt from modules applicable to a
> +particular system and how to build on top of it. Also explained is how to fork
> +the policy to form a new base for building a customised target policy.
> +
> +## The Android Project
> +
> +This is fully discussed in the
> +[**SE for Android**](seandroid.md#security-enhancements-for-android) section
> +with a section below that explains
> +[**Building A Sample Android Policy**](#building-a-sample-android-policy) to
> +examine its construction.
> +
> +## Building A Small Monolithic Reference Policy
> +
> +This section describes how a smaller monolithic Reference Policy can be built
> +as a starter policy. It supports the minimum of policy modules that can be
> +defined in a *modules.conf* file, this file is described in the
> +[**Reference Policy Build Options -** *policy/modules.conf*](#reference-policy-build-options---policymodules.conf)
> +section.
> +
> +To start download the Reference Policy source:
> +
> +```
> +git clone https://github.com/SELinuxProject/refpolicy.git
> +cd refpolicy
> +```
> +
> +For the initial configuration, either replace the current *build.conf*
> +file with the sample
> +[***build.conf***](notebook-examples/embedded-policy/reference-policy/build.conf)
> +or edit the current *build.conf* file to the requirements (e.g. MONOLITHIC = y)
> +
> +Install the source policy in the build directory:
> +
> +```
> +make install-src
> +cd /etc/selinux/<NAME>/src/policy
> +```
> +
> +The following mandatory *make conf* step will build the initial
> +*policy/booleans.conf* and *policy/modules.conf* files.
> +
> +This process will also build the *policy/modules/kernel/corenetwork.te* and
> +*corenetwork.if* files. These would be based on the contents of
> +*corenetwork.te.in* and *corenetwork.if.in* configuration files.
> +
> +For this build only the *policy/modules.conf* will be replaced with the
> +sample version.
> +
> +```
> +make conf
> +```
> +
> +Replace the current *policy/modules.conf* with the sample
> +[***modules.conf***](notebook-examples/embedded-policy/reference-policy/modules.conf)
> +and run:
> +
> +```
> +make install
> +```
> +
> +The binary policy will now be built in the */etc/selinux/\<NAME\>/policy*
> +directory. The */etc/selinux/\<NAME\>/src/policy/policy.conf* file contains
> +the policy language statements used to generate the binary policy.
> +
> +The *policy.conf* file can be examined with a text editor and the binary
> +*policy.\<ver\>* file can be viewed using tools such as ***apol**(1)*.
> +
> +### Adding Additional Modules
> +
> +Note that if the *modules.conf* file is modified to add additional modules,
> +*make clean* MUST be run before *make install* or *make load*.
> +
> +The ease of adding additional modules to the *policy/modules.conf* file depends
> +on the modules dependencies, for example to add the *ftp* module:
> +
> +```
> +# Layer: services
> +# Module: ftp
> +#
> +# File transfer protocol service.
> +#
> +ftp = module
> +```
> +
> +Now run:
> +
> +```
> +make clean
> +make install
> +```
> +
> +to build the policy, this will flag a dependency error:
> +
> +```
> +policy/modules/services/ftp.te:488:ERROR 'type ssh_home_t is not within scope'
> +```
> +
> +This shows that the *ftp* module relies on the *ssh* module, therefore need to
> +also add:
> +
> +```
> +# Layer: services
> +# Module: ssh
> +#
> +# Secure shell client and server policy.
> +#
> +ssh = module
> +```
> +
> +Now run:
> +
> +```
> +make clean
> +make install
> +```
> +
> +This should build a valid policy. Although note that adding some modules will
> +lead to a string of dependent modules.
> +
> +If a suitable module cannot be found in the *policy/modules* directory, then
> +one can be generated and added to the store. To generate policy modules using
> +output from the audit log, see ***audit2allow**(1)* (however review any policy
> +generated). The
> +[**Reference Policy**](reference_policy.md#the-reference-policy) section
> +explains the format of these module files.
> +
> +### The Clean-up
> +
> +Once a policy is complete it could be cleaned up by removing components
> +that are not required for example:
> +
> +- The *file_contexts* generated will have entries that could be deleted.
> +- Unused boleans could be removed.
> +- Review Policy Capabilities.
> +- Remove unused classes and permissions (*policy/flask/security_classes* and
> + *policy/flask/access_vectors*).
> +- There are a number of policy configuration files that can be removed within
> + *etc/selinux/refpolicy* (e.g. *etc/selinux/refpolicy/contexts/x_contexts*).
> +
> +These will probably amount to small fry, but every little helps!!
> +
> +## Building A Sample Android Policy
> +
> +A purpose built embedded policy example is the Android policy that is
> +discussed in the
> +[**SE for Android**](seandroid.md#security-enhancements-for-android) section.
> +This policy has become more complex over time, however they did start with a
> +basic policy that can be explored as described below that does not require
> +obtaining the full AOSP source and build environment.
> +
> +[**Android - The SELinux Policy**](seandroid.md#the-selinux-policy) section
> +descibes how an Android policy is constructed using ***m4**(1)* macros, *\*.te*
> +files etc., similar to the
> +[**Reference Policy**](reference_policy.md#the-reference-policy).
> +
> +To build a sample policy for inspection:
> +
> +- Obtain a copy of the Android policy built for 4.1, note that only the core
> + policy is built here as Android adds device specific policy modules as per
> + its build configuration (an example build with a device is shown later).
> +
> +```
> +git clone https://android.googlesource.com/platform/external/sepolicy
> +cd sepolicy
> +git checkout android-4.1.1_r1
> +```
> +
> +- Copy the text below into a
> + [*Makefile*](notebook-examples/embedded-policy/android-policy/android-4/Makefile)
> + installed in the *sepolicy* directory.
> +
> +```
> +build_policy:
> + m4 -D mls_num_sens=1 \
> + -D mls_num_cats=1024 \
> + -s security_classes \
> + initial_sids \
> + access_vectors \
> + global_macros \
> + mls_macros \
> + mls \
> + policy_capabilities \
> + te_macros \
> + attributes \
> + *.te \
> + roles \
> + users \
> + ocontexts > policy.conf
> + checkpolicy -U deny -M -o sepolicy policy.conf
> +```
> +
> +- Run *make* to build the policy. There should be a *policy.conf* file that
> + can be examined with a text editor and a binary *sepolicy* policy
> + file that can be viewed using tools such as ***apol**(1)*.
> + Note the order in which the *policy.conf* file is built as it conforms to
> + the layout described in the
> + [**Kernel Policy Language**](kernel_policy_language.md#policy-source-files)
> + section.
> +
> +Over time the Android policy locked down more and more processes and then
> +became more complex as policy version control was required when upgrading.
> +The **Brillo** release was their first IoT release and can be built using the
> +instructions in the
> +[*brillo/Makefile*](notebook-examples/embedded-policy/android-policy/brillo/Makefile)
> +To build a policy containing a device, follow the instructions in the
> +[*brillo-device/Makefile*](notebook-examples/embedded-policy/android-policy/brillo-device/Makefile)
> +as a device policy must be obtained from the Android repository.
> +
> +Later Android split policy into private and public segments, they also used
> +CIL for some policy components as described in the
> +[**Android - The SELinux Policy**](seandroid.md#the-selinux-policy) section.
> +The **Android 10** release policy is an example where this split policy is used.
> +This can be built using the instructions in the
> +[*android-10/Makefile*](notebook-examples/embedded-policy/android-policy/android-10/Makefile).
> +
> +[^fn_em_1]: An example of this integration is setting a new process context as
> +shown in the Zygote code:
> +<https://android.googlesource.com/platform/frameworks/base/+/refs/heads/android10-dev/core/jni/com_android_internal_os_Zygote.cpp#1095>.
> +The [**SE for Android**](seandroid.md#security-enhancements-for-android) section
> +explains SELinux integration within Android AOSP services.
> +
> +[^fn_em_2]: The 'policy store' holds policy modules in 'policy package' format
> +(*\*.pp* files).
> +
> +[^fn_em_3]: The 'policy store' holds policy modules as compressed CIL text files.
> +
> +<!-- %CUTHERE% -->
> +
> +---
> +**[[ PREV ]](implementing_seaware_apps.md)** **[[ TOP ]](#)** **[[ NEXT ]](seandroid.md)**
> diff --git a/src/implementing_seaware_apps.md b/src/implementing_seaware_apps.md
> index ee38258..924df16 100644
> --- a/src/implementing_seaware_apps.md
> +++ b/src/implementing_seaware_apps.md
> @@ -296,4 +296,4 @@ applied to their objects as defined by policy.
> <!-- %CUTHERE% -->
>
> ---
> -**[[ PREV ]](reference_policy.md)** **[[ TOP ]](#)** **[[ NEXT ]](seandroid.md)**
> +**[[ PREV ]](reference_policy.md)** **[[ TOP ]](#)** **[[ NEXT ]](embedded_systems.md)**
> diff --git a/src/notebook-examples/embedded-policy/android-policy/README.md b/src/notebook-examples/embedded-policy/android-policy/README.md
> new file mode 100644
> index 0000000..43bc2d8
> --- /dev/null
> +++ b/src/notebook-examples/embedded-policy/android-policy/README.md
> @@ -0,0 +1,34 @@
> +# Android Policy
> +
> +The Android policies defined in these *Makefile* files will allow them to be
> +built for inspection without obtaining the full AOSP source and build
> +environment.
> +
> +Note that the core policy is built in most cases as within Android each
> +device adds their specific policy modules.
> +
> +The build process will produce two files:
> +
> +- *policy.conf* that can be examined with a text editor.
> +- *sepolicy* that can be viewed using tools such as ***apol**(1)*.
> +
> +The ***git**(1)* commands required to obtain the policies are defined in
> +each *Makefile*.
> +
> +- *android-4/Makefile*
> + - The initial Android basic policy.
> +
> +- *brillo/Makefile*
> + - The Brillo release was their first IoT release.
> +
> +- *android-10/Makefile*
> + - The Android 10 release split the policy into private and public segments
> + and has started using some CIL modules (although for simplicity they are
> + not built).
> +
> +## Build policy with a Device
> +
> +The *brillo-device/Makefile* has instructions to build the Brillo policy with
> +a suitable device using the
> +*https://android.googlesource.com/platform/external/sepolicy/+archive/refs/heads/brillo-m7-release.tar.gz*
> +device policy file.
> diff --git a/src/notebook-examples/embedded-policy/android-policy/android-10/Makefile b/src/notebook-examples/embedded-policy/android-policy/android-10/Makefile
> new file mode 100644
> index 0000000..b13b6ad
> --- /dev/null
> +++ b/src/notebook-examples/embedded-policy/android-policy/android-10/Makefile
> @@ -0,0 +1,42 @@
> +#### Build android-10 base policy Makefile ####
> +
> +# git clone https://android.googlesource.com/platform/system/sepolicy
> +# cd sepolicy
> +# git checkout android10-dev
> +# Copy this Makefile to the sepolicy directory and run 'make' to build the
> +# policy files.
> +#
> +# The policy.conf file can be examined with a text editor and the binary
> +# sepolicy file can be viewed using tools such as apol(1).
> +#
> +# Note this is built with 'target_build_variant=user' and will not have the
> +# 'su' permissive domain. Set to 'eng' to add 'su' permissive domain.
> +
> +build_policy:
> + m4 -D mls_num_sens=1 \
> + -D mls_num_cats=1024 \
> + -D target_build_variant=user \
> + -D target_recovery=false \
> + -s private/security_classes \
> + private/initial_sids \
> + private/access_vectors \
> + public/global_macros \
> + public/neverallow_macros \
> + private/mls_macros \
> + private/mls_decl \
> + private/mls \
> + private/policy_capabilities \
> + public/te_macros \
> + public/attributes \
> + public/ioctl_defines \
> + public/ioctl_macros \
> + public/*.te \
> + private/*.te \
> + private/roles_decl \
> + public/roles \
> + private/users \
> + private/initial_sid_contexts \
> + private/fs_use \
> + private/genfs_contexts \
> + private/port_contexts > policy.conf
> + checkpolicy -U deny -M -o sepolicy policy.conf
> diff --git a/src/notebook-examples/embedded-policy/android-policy/android-4/Makefile b/src/notebook-examples/embedded-policy/android-policy/android-4/Makefile
> new file mode 100644
> index 0000000..40fbccb
> --- /dev/null
> +++ b/src/notebook-examples/embedded-policy/android-policy/android-4/Makefile
> @@ -0,0 +1,31 @@
> +#### Build android-4.1.1_r1 base policy Makefile ####
> +
> +# git clone https://android.googlesource.com/platform/external/sepolicy
> +# cd sepolicy
> +# git checkout android-4.1.1_r1
> +# Copy this Makefile to the sepolicy directory and run 'make' to build the
> +# policy files.
> +#
> +# The policy.conf file can be examined with a text editor and the binary
> +# sepolicy file can be viewed using tools such as apol(1).
> +
> +build_policy:
> + #
> + # Note the order in which the policy.conf file is built:
> + #
> + m4 -D mls_num_sens=1 \
> + -D mls_num_cats=1024 \
> + -s security_classes \
> + initial_sids \
> + access_vectors \
> + global_macros \
> + mls_macros \
> + mls \
> + policy_capabilities \
> + te_macros \
> + attributes \
> + *.te \
> + roles \
> + users \
> + ocontexts > policy.conf
> + checkpolicy -U deny -M -o sepolicy policy.conf
> diff --git a/src/notebook-examples/embedded-policy/android-policy/brillo-device/Makefile b/src/notebook-examples/embedded-policy/android-policy/brillo-device/Makefile
> new file mode 100644
> index 0000000..271cc5c
> --- /dev/null
> +++ b/src/notebook-examples/embedded-policy/android-policy/brillo-device/Makefile
> @@ -0,0 +1,46 @@
> +#### Build brillo-m10 + device policy Makefile ####
> +
> +# git clone https://android.googlesource.com/platform/external/sepolicy
> +# cd sepolicy
> +# git checkout brillo-m10-release
> +# Copy this Makefile to the sepolicy directory and run 'make' to build the
> +# policy files.
> +#
> +# To obtain a buildable device the brillo-m7-dev tar file is downloaded and
> +# installed into the sepolicy directory.
> +#
> +# The policy.conf file can be examined with a text editor and the binary
> +# sepolicy file can be viewed using tools such as apol(1).
> +
> +DEV_DIR := brillo-m7-dev
> +
> +build_policy:
> + mkdir -p $(DEV_DIR)
> + wget https://android.googlesource.com/device/generic/brillo/+archive/refs/heads/brillo-m7-dev.tar.gz -O - | tar -C $(DEV_DIR) -xz
> + m4 -D mls_num_sens=1 \
> + -D mls_num_cats=1024 \
> + -D target_build_variant=eng \
> + -D target_recovery=false \
> + -s security_classes \
> + $(DEV_DIR)/sepolicy/security_classes \
> + initial_sids \
> + access_vectors \
> + $(DEV_DIR)/sepolicy/access_vectors \
> + global_macros \
> + mls_macros \
> + mls \
> + policy_capabilities \
> + te_macros \
> + $(DEV_DIR)/sepolicy/te_macros \
> + neverallow_macros \
> + attributes \
> + ioctl_macros \
> + *.te \
> + $(DEV_DIR)/sepolicy/*.te \
> + roles \
> + users \
> + initial_sid_contexts \
> + fs_use \
> + genfs_contexts \
> + port_contexts > policy.conf
> + checkpolicy -U deny -M -o sepolicy policy.conf
> diff --git a/src/notebook-examples/embedded-policy/android-policy/brillo/Makefile b/src/notebook-examples/embedded-policy/android-policy/brillo/Makefile
> new file mode 100644
> index 0000000..b715db0
> --- /dev/null
> +++ b/src/notebook-examples/embedded-policy/android-policy/brillo/Makefile
> @@ -0,0 +1,38 @@
> +#### Build brillo-m10 base policy Makefile ####
> +
> +# git clone https://android.googlesource.com/platform/external/sepolicy
> +# cd sepolicy
> +# git checkout brillo-m10-release
> +# Copy this Makefile to the sepolicy directory and run 'make' to build the
> +# policy files.
> +#
> +# The policy.conf file can be examined with a text editor and the binary
> +# sepolicy file can be viewed using tools such as apol(1).
> +#
> +# Note this is built with 'target_build_variant=eng' and will have the 'su'
> +# permissive domain. Set to 'user' to remove the 'su' permissive domain.
> +
> +build_policy:
> + m4 -D mls_num_sens=1 \
> + -D mls_num_cats=1024 \
> + -D target_build_variant=eng \
> + -D target_recovery=false \
> + -s security_classes \
> + initial_sids \
> + access_vectors \
> + global_macros \
> + mls_macros \
> + mls \
> + policy_capabilities \
> + te_macros \
> + neverallow_macros \
> + attributes \
> + ioctl_macros \
> + *.te \
> + roles \
> + users \
> + initial_sid_contexts \
> + fs_use \
> + genfs_contexts \
> + port_contexts > policy.conf
> + checkpolicy -U deny -M -o sepolicy policy.conf
> diff --git a/src/notebook-examples/embedded-policy/reference-policy/README.md b/src/notebook-examples/embedded-policy/reference-policy/README.md
> new file mode 100644
> index 0000000..6d78a58
> --- /dev/null
> +++ b/src/notebook-examples/embedded-policy/reference-policy/README.md
> @@ -0,0 +1,6 @@
> +# Building A Small Monolithic Reference Policy
> +
> +The *modules.conf* file supports the minimum of policy modules that can be
> +defined to build a small monolithic policy as described in the
> +[Building A Small Monolithic Reference Policy](embedded_systems.md#building-a-small-monolithic-reference-policy)
> +section.
> diff --git a/src/notebook-examples/embedded-policy/reference-policy/build.conf b/src/notebook-examples/embedded-policy/reference-policy/build.conf
> new file mode 100644
> index 0000000..f6d0f46
> --- /dev/null
> +++ b/src/notebook-examples/embedded-policy/reference-policy/build.conf
> @@ -0,0 +1,84 @@
> +########################################
> +#
> +# Policy build options
> +#
> +
> +# Policy version
> +# By default, checkpolicy will create the highest
> +# version policy it supports. Setting this will
> +# override the version. This only has an
> +# effect for monolithic policies.
> +#OUTPUT_POLICY = 18
> +
> +# Policy Type
> +# standard, mls, mcs
> +TYPE = standard
> +
> +# Policy Name
> +# If set, this will be used as the policy
> +# name. Otherwise the policy type will be
> +# used for the name.
> +NAME = refpolicy
> +
> +# Distribution
> +# Some distributions have portions of policy
> +# for programs or configurations specific to the
> +# distribution. Setting this will enable options
> +# for the distribution.
> +# redhat, gentoo, debian, suse, and rhel4 are current options.
> +# Fedora users should enable redhat.
> +#DISTRO = redhat
> +
> +# Unknown Permissions Handling
> +# The behavior for handling permissions defined in the
> +# kernel but missing from the policy. The permissions
> +# can either be allowed, denied, or the policy loading
> +# can be rejected.
> +# allow, deny, and reject are current options.
> +UNK_PERMS = deny
> +
> +# Direct admin init
> +# Setting this will allow sysadm to directly
> +# run init scripts, instead of requiring run_init.
> +# This is a build option, as role transitions do
> +# not work in conditional policy.
> +DIRECT_INITRC = n
> +
> +# Systemd
> +# Setting this will configure systemd as the init system.
> +SYSTEMD = n
> +
> +# Build monolithic policy. Putting y here
> +# will build a monolithic policy.
> +MONOLITHIC = y
> +
> +# User-based access control (UBAC)
> +# Enable UBAC for role separations.
> +UBAC = n
> +
> +# Custom build options. This field enables custom
> +# build options. Putting foo here will enable
> +# build option blocks named foo. Options should be
> +# separated by spaces.
> +CUSTOM_BUILDOPT =
> +
> +# Number of MLS Sensitivities
> +# The sensitivities will be s0 to s(MLS_SENS-1).
> +# Dominance will be in increasing numerical order
> +# with s0 being lowest.
> +MLS_SENS = 16
> +
> +# Number of MLS Categories
> +# The categories will be c0 to c(MLS_CATS-1).
> +MLS_CATS = 1024
> +
> +# Number of MCS Categories
> +# The categories will be c0 to c(MLS_CATS-1).
> +MCS_CATS = 1024
> +
> +# Set this to y to only display status messages
> +# during build.
> +QUIET = n
> +
> +# Set this to treat warnings as errors.
> +WERROR = n
> diff --git a/src/notebook-examples/embedded-policy/reference-policy/modules.conf b/src/notebook-examples/embedded-policy/reference-policy/modules.conf
> new file mode 100644
> index 0000000..091a22b
> --- /dev/null
> +++ b/src/notebook-examples/embedded-policy/reference-policy/modules.conf
> @@ -0,0 +1,236 @@
> +#
> +# This file contains a listing of available modules.
> +# To prevent a module from being used in policy
> +# creation, set the module name to "off".
> +#
> +# For monolithic policies, modules set to "base" and "module"
> +# will be built into the policy.
> +#
> +# For modular policies, modules set to "base" will be
> +# included in the base module. "module" will be compiled
> +# as individual loadable modules.
> +#
> +
> +# Layer: kernel
> +# Module: corecommands
> +# Required in base
> +#
> +# Core policy for shells, and generic programs
> +# in /bin, /sbin, /usr/bin, and /usr/sbin.
> +#
> +corecommands = base
> +
> +# Layer: kernel
> +# Module: corenetwork
> +# Required in base
> +#
> +# Policy controlling access to network objects
> +#
> +corenetwork = base
> +
> +# Layer: kernel
> +# Module: devices
> +# Required in base
> +#
> +# Device nodes and interfaces for many basic system devices.
> +#
> +devices = base
> +
> +# Layer: kernel
> +# Module: domain
> +# Required in base
> +#
> +# Core policy for domains.
> +#
> +domain = base
> +
> +# Layer: kernel
> +# Module: files
> +# Required in base
> +#
> +# Basic filesystem types and interfaces.
> +#
> +files = base
> +
> +# Layer: kernel
> +# Module: filesystem
> +# Required in base
> +#
> +# Policy for filesystems.
> +#
> +filesystem = base
> +
> +# Layer: kernel
> +# Module: kernel
> +# Required in base
> +#
> +# Policy for kernel threads, proc filesystem,
> +# and unlabeled processes and objects.
> +#
> +kernel = base
> +
> +# Layer: kernel
> +# Module: mcs
> +# Required in base
> +#
> +# Multicategory security policy
> +#
> +mcs = base
> +
> +# Layer: kernel
> +# Module: mls
> +# Required in base
> +#
> +# Multilevel security policy
> +#
> +mls = base
> +
> +# Layer: kernel
> +# Module: selinux
> +# Required in base
> +#
> +# Policy for kernel security interface, in particular, selinuxfs.
> +#
> +selinux = base
> +
> +# Layer: kernel
> +# Module: terminal
> +# Required in base
> +#
> +# Policy for terminals.
> +#
> +terminal = base
> +
> +# Layer: kernel
> +# Module: ubac
> +# Required in base
> +#
> +# User-based access control policy
> +#
> +ubac = base
> +
> +# Layer: kernel
> +# Module: storage
> +#
> +# Policy controlling access to storage devices
> +#
> +storage = module
> +
> +# Layer: system
> +# Module: application
> +#
> +# Policy for user executable applications.
> +#
> +application = module
> +
> +# Layer: system
> +# Module: authlogin
> +#
> +# Common policy for authentication and user login.
> +#
> +authlogin = module
> +
> +# Layer: system
> +# Module: clock
> +#
> +# Policy for reading and setting the hardware clock.
> +#
> +clock = module
> +
> +# Layer: system
> +# Module: getty
> +#
> +# Manages physical or virtual terminals.
> +#
> +getty = module
> +
> +# Layer: system
> +# Module: init
> +#
> +# System initialization programs (init and init scripts).
> +#
> +init = module
> +
> +# Layer: system
> +# Module: libraries
> +#
> +# Policy for system libraries.
> +#
> +libraries = module
> +
> +# Layer: system
> +# Module: locallogin
> +#
> +# Policy for local logins.
> +#
> +locallogin = module
> +
> +# Layer: system
> +# Module: logging
> +#
> +# Policy for the kernel message logger and system logging daemon.
> +#
> +logging = module
> +
> +# Layer: system
> +# Module: miscfiles
> +#
> +# Miscellaneous files.
> +#
> +miscfiles = module
> +
> +# Layer: system
> +# Module: modutils
> +#
> +# Policy for kernel module utilities
> +#
> +modutils = module
> +
> +# Layer: system
> +# Module: mount
> +#
> +# Policy for mount.
> +#
> +mount = module
> +
> +# Layer: system
> +# Module: selinuxutil
> +#
> +# Policy for SELinux policy and userland applications.
> +#
> +selinuxutil = module
> +
> +# Layer: system
> +# Module: sysnetwork
> +#
> +# Policy for network configuration: ifconfig and dhcp client.
> +#
> +sysnetwork = module
> +
> +# Layer: system
> +# Module: udev
> +#
> +# Policy for udev.
> +#
> +udev = module
> +
> +# Layer: system
> +# Module: unconfined
> +#
> +# The unconfined domain.
> +#
> +unconfined = module
> +
> +# Layer: system
> +# Module: userdomain
> +#
> +# Policy for user domains
> +#
> +userdomain = module
> +
> +# Layer: roles
> +# Module: sysadm
> +#
> +# General system administration role
> +#
> +sysadm = module
> diff --git a/src/seandroid.md b/src/seandroid.md
> index 409afe0..dc90513 100644
> --- a/src/seandroid.md
> +++ b/src/seandroid.md
> @@ -76,9 +76,9 @@ idea of the scope.
>
> Provides the SELinux userspace function library that is installed on the
> device. It has additional functions to support Android as summarised in
> -*external/selinux/README.android*. It is build from a merged upstream version
> +*external/selinux/README.android*. It is built from a merged upstream version
> (<https://github.com/SELinuxProject/selinux>) with Android specific additions
> -such as:
> +(<https://android.googlesource.com/platform/external/selinux/>) such as:
>
> ***selinux_android_setcontext()***
>
> @@ -160,7 +160,7 @@ There are no specific updates to support Android except an *Android.bp* file.
> ### ***bootable/recovery***
>
> Changes to manage file labeling on recovery using functions such as
> -***selinux_android_file_context_handle()**, ***selabel_lookup**(3)* and
> +**selinux_android_file_context_handle()**, ***selabel_lookup**(3)* and
> ***setfscreatecon**(3)*.
>
> ### ***build***
> @@ -210,6 +210,10 @@ The Android specific object classes are described in the
> [**Android Classes & Permissions**](#android-classes-permissions)
> section.
>
> +The [**Embedded Systems - Building A Sample Android Policy**](embedded-systems#building-a-sample-android-policy)
> +section explains how to build basic Android policies. These can be explored
> +without requiring the full AOSP source and build environment.
> +
> ### ***kernel***
>
> All Android kernels support the Linux Security Module (LSM) and SELinux
> @@ -1593,4 +1597,4 @@ USERDEBUG : $DEFAULT_SYSTEM_DEV_CERTIFICATE/testkey.x509.pem
> <!-- %CUTHERE% -->
>
> ---
> -**[[ PREV ]](implementing_seaware_apps.md)** **[[ TOP ]](#)** **[[ NEXT ]](object_classes_permissions.md)**
> +**[[ PREV ]](embedded_systems.md)** **[[ TOP ]](#)** **[[ NEXT ]](object_classes_permissions.md)**
> diff --git a/src/section_list.txt b/src/section_list.txt
> index 340e516..dcca883 100644
> --- a/src/section_list.txt
> +++ b/src/section_list.txt
> @@ -53,6 +53,7 @@ xen_statements.md
> modular_policy_statements.md
> reference_policy.md
> implementing_seaware_apps.md
> +embedded_systems.md
> seandroid.md
> object_classes_permissions.md
> libselinux_functions.md
> diff --git a/src/toc.md b/src/toc.md
> index d915b42..f5778bd 100644
> --- a/src/toc.md
> +++ b/src/toc.md
> @@ -54,6 +54,7 @@
> - [Modular Policy Support Statements](modular_policy_statements.md#modular-policy-support-statements)
> - [The Reference Policy](reference_policy.md#the-reference-policy)
> - [Implementing SELinux-aware Applications](implementing_seaware_apps.md#implementing-selinux-aware-applications)
> +- [Embedded Systems](embedded_systems.md#embedded-systems)
> - [SE for Android](seandroid.md#security-enhancements-for-android)
> - [Appendix A - Object Classes and Permissions](object_classes_permissions.md#appendix-a---object-classes-and-permissions)
> - [Appendix B - *libselinux* API Summary](libselinux_functions.md#appendix-b---libselinux-api-summary)
--
gpg --locate-keys [email protected]
Key fingerprint = FCD2 3660 5D6B 9D27 7FC6 E0FF DA7E 521F 10F6 4098
https://sks-keyservers.net/pks/lookup?op=get&search=0xDA7E521F10F64098
Dominick Grift
On Tue, 2021-02-09 at 18:38 +0100, Dominick Grift wrote:
> Richard Haines <[email protected]> writes:
>
> > Add a new section and supporting examples for embedded systems.
>
> Looks good. Thanks
>
> I will probably submit a patch once this one is committed that
> expands a
> little on the OpenWrt scenario.
This patch has already been commited by Paul on 27th Jan. This
particular email was sent on the 25th Jan but got lost so I resent.
Looks like this one only took 14 days to finally get delivered.
On Wed, Feb 10, 2021 at 10:01 AM Richard Haines
<[email protected]> wrote:
> On Tue, 2021-02-09 at 18:38 +0100, Dominick Grift wrote:
> > Richard Haines <[email protected]> writes:
> >
> > > Add a new section and supporting examples for embedded systems.
> >
> > Looks good. Thanks
> >
> > I will probably submit a patch once this one is committed that
> > expands a
> > little on the OpenWrt scenario.
>
> This patch has already been commited by Paul on 27th Jan.
I just got done double checking to make sure this patch was merged; I
saw Dominick's reply and worried that I forgot to do the 'git push'
after merging :)
> This
> particular email was sent on the 25th Jan but got lost so I resent.
> Looks like this one only took 14 days to finally get delivered.
E-mail, it's just like real mail!
--
paul moore
http://www.paul-moore.com