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
On Wed, Jan 27, 2021 at 10:33 AM Richard Haines
<[email protected]> wrote:
>
> 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
This is great guys - thank you!
--
paul moore
http://www.paul-moore.com