1# Android SEPolicy 2 3This directory contains the core Android SELinux policy configuration. 4It defines the domains and types for the AOSP services and apps common to 5all devices. Device-specific policy should be placed under a 6separate `device/<vendor>/<board>/sepolicy` subdirectory and linked 7into the policy build as described below. 8 9## Policy Generation 10 11Additional, per device, policy files can be added into the 12policy build. These files should have each line including the 13final line terminated by a newline character (`0x0A`). This 14will allow files to be concatenated and processed whenever 15the `m4`(1) macro processor is called by the build process. 16Adding the newline will also make the intermediate text files 17easier to read when debugging build failures. The sets of file, 18service and property contexts files will automatically have a 19newline inserted between each file as these are common failure 20points. 21 22These device policy files can be configured through the use of 23the `BOARD_VENDOR_SEPOLICY_DIRS` variable. This variable should be set 24in the BoardConfig.mk file in the device or vendor directories. 25 26`BOARD_VENDOR_SEPOLICY_DIRS` contains a list of directories to search 27for additional policy files. Order matters in this list. 28For example, if you have 2 instances of widget.te files in the 29`BOARD_VENDOR_SEPOLICY_DIRS` search path, then the first one found (at the 30first search dir containing the file) will be concatenated first. 31Reviewing `out/target/product/<device>/obj/ETC/vendor_sepolicy.conf_intermediates/vendor_sepolicy.conf` 32will help sort out ordering issues. 33 34Example `BoardConfig.mk` Usage: 35From the Tuna device `BoardConfig.mk`, `device/samsung/tuna/BoardConfig.mk` 36 37 BOARD_VENDOR_SEPOLICY_DIRS += device/samsung/tuna/sepolicy 38 39Alongside vendor sepolicy dirs, OEMs can also amend the public and private 40policy of the product and system_ext partitions: 41 42 SYSTEM_EXT_PUBLIC_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/systemext/public 43 SYSTEM_EXT_PRIVATE_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/systemext/private 44 PRODUCT_PUBLIC_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/product/public 45 PRODUCT_PRIVATE_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/product/private 46 47The old `BOARD_PLAT_PUBLIC_SEPOLICY_DIR` and `BOARD_PLAT_PRIVATE_SEPOLICY_DIR` 48variables have been deprecated in favour of `SYSTEM_EXT_*`. 49 50Additionally, OEMs can specify `BOARD_SEPOLICY_M4DEFS` to pass arbitrary `m4` 51definitions during the build. A definition consists of a string in the form 52of `macro-name=value`. Spaces must **NOT** be present. This is useful for building modular 53policies, policy generation, conditional file paths, etc. It is supported in 54the following file types: 55* All `*.te` and SELinux policy files as passed to `checkpolicy` 56* `file_contexts` 57* `service_contexts` 58* `property_contexts` 59* `keys.conf` 60 61Example BoardConfig.mk Usage: 62 63 BOARD_SEPOLICY_M4DEFS += btmodule=foomatic \ 64 btdevice=/dev/gps 65 66## SPECIFIC POLICY FILE INFORMATION 67 68### mac_permissions.xml 69The `mac_permissions.xml` file is used for controlling the mmac solutions 70as well as mapping a public base16 signing key with an arbitrary seinfo 71string. Details of the files contents can be found in a comment at the 72top of that file. The seinfo string, previously mentioned, is the same string 73that is referenced in seapp_contexts. 74 75It is important to note the final processed version of this file 76is stripped of comments and whitespace. This is to preserve space on the 77system.img. If one wishes to view it in a more human friendly format, 78the `tidy` or `xmllint` command will assist you. 79 80### insertkeys.py 81Is a helper script for mapping arbitrary tags in the signature stanzas of 82`mac_permissions.xml` to public keys found in pem files. This script takes 83a `mac_permissions.xml` file(s) and configuration file in order to operate. 84Details of the configuration file (`keys.conf`) can be found in the subsection 85keys.conf. This tool is also responsible for stripping the comments and 86whitespace during processing. 87 88### keys.conf 89The `keys.conf` file is used for controlling the mapping of "tags" found in 90the `mac_permissions.xml` signature stanzas with actual public keys found in 91pem files. The configuration file is processed via `m4`. 92 93The script allows for mapping any string contained in `TARGET_BUILD_VARIANT` 94with specific path to a pem file. Typically `TARGET_BUILD_VARIANT` is either 95user, eng or userdebug. Additionally, one can specify "ALL" to map a path to 96any string specified in `TARGET_BUILD_VARIANT`. All tags are matched verbatim 97and all options are matched lowercase. The options are **tolowered** automatically 98for the user, it is convention to specify tags and options in all uppercase 99and tags start with @. The option arguments can also use environment variables 100via the familiar `$VARIABLE` syntax. This is often useful for setting a location 101to ones release keys. 102 103Often times, one will need to integrate an application that was signed by a separate 104organization and may need to extract the pem file for the `insertkeys/keys.conf` tools. 105Extraction of the public key in the pem format is possible via `openssl`. First you need 106to unzip the apk, once it is unzipped, `cd` into the `META_INF` directory and then execute 107 108 openssl pkcs7 -inform DER -in CERT.RSA -out CERT.pem -outform PEM -print_certs 109 110On some occasions `CERT.RSA` has a different name, and you will need to adjust for that. 111After extracting the pem, you can rename it, and configure `keys.conf` and 112`mac_permissions.xml` to pick up the change. You **MUST** open the generated pem file in a text 113editor and strip out anything outside the opening and closing scissor lines. Failure to do 114so **WILL** cause a compile time issue thrown by insertkeys.py 115 116**NOTE:** The pem files are base64 encoded and `PackageManagerService`, `mac_permissions.xml` 117 and `setool` all use base16 encodings. 118