Richard Haines <richard_c_haines@xxxxxxxxxxxxxx> 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 <richard_c_haines@xxxxxxxxxxxxxx> > --- > 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 dominick.grift@xxxxxxxxxxx Key fingerprint = FCD2 3660 5D6B 9D27 7FC6 E0FF DA7E 521F 10F6 4098 https://sks-keyservers.net/pks/lookup?op=get&search=0xDA7E521F10F64098 Dominick Grift
