Convert README to README.md
Just a format change. The contents are copy-and-pasted as-is. Bug: 196944893 Test: N/A Change-Id: I4d898d5bae784a8cf2087c7fdeaff7493eb2aa62
This commit is contained in:
Inseob Kim
parent
90bc7c36d9
commit
1851dcb2ee
2 changed files with 117 additions and 114 deletions
114
README
114
README
|
|
@ -1,114 +0,0 @@
|
||||||
This directory contains the core Android SELinux policy configuration.
|
|
||||||
It defines the domains and types for the AOSP services and apps common to
|
|
||||||
all devices. Device-specific policy should be placed under a
|
|
||||||
separate device/<vendor>/<board>/sepolicy subdirectory and linked
|
|
||||||
into the policy build as described below.
|
|
||||||
|
|
||||||
Policy Generation:
|
|
||||||
|
|
||||||
Additional, per device, policy files can be added into the
|
|
||||||
policy build. These files should have each line including the
|
|
||||||
final line terminated by a newline character (0x0A). This
|
|
||||||
will allow files to be concatenated and processed whenever
|
|
||||||
the m4(1) macro processor is called by the build process.
|
|
||||||
Adding the newline will also make the intermediate text files
|
|
||||||
easier to read when debugging build failures. The sets of file,
|
|
||||||
service and property contexts files will automatically have a
|
|
||||||
newline inserted between each file as these are common failure
|
|
||||||
points.
|
|
||||||
|
|
||||||
These device policy files can be configured through the use of
|
|
||||||
the BOARD_VENDOR_SEPOLICY_DIRS variable. This variable should be set
|
|
||||||
in the BoardConfig.mk file in the device or vendor directories.
|
|
||||||
|
|
||||||
BOARD_VENDOR_SEPOLICY_DIRS contains a list of directories to search
|
|
||||||
for additional policy files. Order matters in this list.
|
|
||||||
For example, if you have 2 instances of widget.te files in the
|
|
||||||
BOARD_VENDOR_SEPOLICY_DIRS search path, then the first one found (at the
|
|
||||||
first search dir containing the file) will be concatenated first.
|
|
||||||
Reviewing out/target/product/<device>/obj/ETC/sepolicy_intermediates/policy.conf
|
|
||||||
will help sort out ordering issues.
|
|
||||||
|
|
||||||
Example BoardConfig.mk Usage:
|
|
||||||
From the Tuna device BoardConfig.mk, device/samsung/tuna/BoardConfig.mk
|
|
||||||
|
|
||||||
BOARD_VENDOR_SEPOLICY_DIRS += device/samsung/tuna/sepolicy
|
|
||||||
|
|
||||||
Alongside vendor sepolicy dirs, OEMs can also amend the public and private
|
|
||||||
policy of the product and system_ext partitions:
|
|
||||||
|
|
||||||
SYSTEM_EXT_PUBLIC_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/systemext/public
|
|
||||||
SYSTEM_EXT_PRIVATE_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/systemext/private
|
|
||||||
PRODUCT_PUBLIC_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/product/public
|
|
||||||
PRODUCT_PRIVATE_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/product/private
|
|
||||||
|
|
||||||
The old BOARD_PLAT_PUBLIC_SEPOLICY_DIR and BOARD_PLAT_PRIVATE_SEPOLICY_DIR
|
|
||||||
variables have been deprecated in favour of SYSTEM_EXT_*.
|
|
||||||
|
|
||||||
Additionally, OEMs can specify BOARD_SEPOLICY_M4DEFS to pass arbitrary m4
|
|
||||||
definitions during the build. A definition consists of a string in the form
|
|
||||||
of macro-name=value. Spaces must NOT be present. This is useful for building modular
|
|
||||||
policies, policy generation, conditional file paths, etc. It is supported in
|
|
||||||
the following file types:
|
|
||||||
* All *.te and SE Linux policy files as passed to checkpolicy
|
|
||||||
* file_contexts
|
|
||||||
* service_contexts
|
|
||||||
* property_contexts
|
|
||||||
* keys.conf
|
|
||||||
|
|
||||||
Example BoardConfig.mk Usage:
|
|
||||||
BOARD_SEPOLICY_M4DEFS += btmodule=foomatic \
|
|
||||||
btdevice=/dev/gps
|
|
||||||
|
|
||||||
SPECIFIC POLICY FILE INFORMATION
|
|
||||||
|
|
||||||
mac_permissions.xml:
|
|
||||||
ABOUT:
|
|
||||||
The mac_permissions.xml file is used for controlling the mmac solutions
|
|
||||||
as well as mapping a public base16 signing key with an arbitrary seinfo
|
|
||||||
string. Details of the files contents can be found in a comment at the
|
|
||||||
top of that file. The seinfo string, previously mentioned, is the same string
|
|
||||||
that is referenced in seapp_contexts.
|
|
||||||
|
|
||||||
It is important to note the final processed version of this file
|
|
||||||
is stripped of comments and whitespace. This is to preserve space on the
|
|
||||||
system.img. If one wishes to view it in a more human friendly format,
|
|
||||||
the "tidy" or "xmllint" command will assist you.
|
|
||||||
|
|
||||||
TOOLING:
|
|
||||||
insertkeys.py
|
|
||||||
Is a helper script for mapping arbitrary tags in the signature stanzas of
|
|
||||||
mac_permissions.xml to public keys found in pem files. This script takes
|
|
||||||
a mac_permissions.xml file(s) and configuration file in order to operate.
|
|
||||||
Details of the configuration file (keys.conf) can be found in the subsection
|
|
||||||
keys.conf. This tool is also responsible for stripping the comments and
|
|
||||||
whitespace during processing.
|
|
||||||
|
|
||||||
keys.conf
|
|
||||||
The keys.conf file is used for controlling the mapping of "tags" found in
|
|
||||||
the mac_permissions.xml signature stanzas with actual public keys found in
|
|
||||||
pem files. The configuration file is processed via m4.
|
|
||||||
|
|
||||||
The script allows for mapping any string contained in TARGET_BUILD_VARIANT
|
|
||||||
with specific path to a pem file. Typically TARGET_BUILD_VARIANT is either
|
|
||||||
user, eng or userdebug. Additionally, one can specify "ALL" to map a path to
|
|
||||||
any string specified in TARGET_BUILD_VARIANT. All tags are matched verbatim
|
|
||||||
and all options are matched lowercase. The options are "tolowered" automatically
|
|
||||||
for the user, it is convention to specify tags and options in all uppercase
|
|
||||||
and tags start with @. The option arguments can also use environment variables
|
|
||||||
via the familiar $VARIABLE syntax. This is often useful for setting a location
|
|
||||||
to ones release keys.
|
|
||||||
|
|
||||||
Often times, one will need to integrate an application that was signed by a separate
|
|
||||||
organization and may need to extract the pem file for the insertkeys/keys.conf tools.
|
|
||||||
Extraction of the public key in the pem format is possible via openssl. First you need
|
|
||||||
to unzip the apk, once it is unzipped, cd into the META_INF directory and then execute
|
|
||||||
openssl pkcs7 -inform DER -in CERT.RSA -out CERT.pem -outform PEM -print_certs
|
|
||||||
On some occasions CERT.RSA has a different name, and you will need to adjust for that.
|
|
||||||
After extracting the pem, you can rename it, and configure keys.conf and
|
|
||||||
mac_permissions.xml to pick up the change. You MUST open the generated pem file in a text
|
|
||||||
editor and strip out anything outside the opening and closing scissor lines. Failure to do
|
|
||||||
so WILL cause a compile time issue thrown by insertkeys.py
|
|
||||||
|
|
||||||
NOTE: The pem files are base64 encoded and PackageManagerService, mac_permissions.xml
|
|
||||||
and setool all use base16 encodings.
|
|
||||||
117
README.md
Normal file
117
README.md
Normal file
|
|
@ -0,0 +1,117 @@
|
||||||
|
# Android SEPolicy
|
||||||
|
|
||||||
|
This directory contains the core Android SELinux policy configuration.
|
||||||
|
It defines the domains and types for the AOSP services and apps common to
|
||||||
|
all devices. Device-specific policy should be placed under a
|
||||||
|
separate `device/<vendor>/<board>/sepolicy` subdirectory and linked
|
||||||
|
into the policy build as described below.
|
||||||
|
|
||||||
|
## Policy Generation
|
||||||
|
|
||||||
|
Additional, per device, policy files can be added into the
|
||||||
|
policy build. These files should have each line including the
|
||||||
|
final line terminated by a newline character (`0x0A`). This
|
||||||
|
will allow files to be concatenated and processed whenever
|
||||||
|
the `m4`(1) macro processor is called by the build process.
|
||||||
|
Adding the newline will also make the intermediate text files
|
||||||
|
easier to read when debugging build failures. The sets of file,
|
||||||
|
service and property contexts files will automatically have a
|
||||||
|
newline inserted between each file as these are common failure
|
||||||
|
points.
|
||||||
|
|
||||||
|
These device policy files can be configured through the use of
|
||||||
|
the `BOARD_VENDOR_SEPOLICY_DIRS` variable. This variable should be set
|
||||||
|
in the BoardConfig.mk file in the device or vendor directories.
|
||||||
|
|
||||||
|
`BOARD_VENDOR_SEPOLICY_DIRS` contains a list of directories to search
|
||||||
|
for additional policy files. Order matters in this list.
|
||||||
|
For example, if you have 2 instances of widget.te files in the
|
||||||
|
`BOARD_VENDOR_SEPOLICY_DIRS` search path, then the first one found (at the
|
||||||
|
first search dir containing the file) will be concatenated first.
|
||||||
|
Reviewing `out/target/product/<device>/obj/ETC/vendor_sepolicy.conf_intermediates/vendor_sepolicy.conf`
|
||||||
|
will help sort out ordering issues.
|
||||||
|
|
||||||
|
Example `BoardConfig.mk` Usage:
|
||||||
|
From the Tuna device `BoardConfig.mk`, `device/samsung/tuna/BoardConfig.mk`
|
||||||
|
|
||||||
|
BOARD_VENDOR_SEPOLICY_DIRS += device/samsung/tuna/sepolicy
|
||||||
|
|
||||||
|
Alongside vendor sepolicy dirs, OEMs can also amend the public and private
|
||||||
|
policy of the product and system_ext partitions:
|
||||||
|
|
||||||
|
SYSTEM_EXT_PUBLIC_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/systemext/public
|
||||||
|
SYSTEM_EXT_PRIVATE_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/systemext/private
|
||||||
|
PRODUCT_PUBLIC_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/product/public
|
||||||
|
PRODUCT_PRIVATE_SEPOLICY_DIRS += device/acme/roadrunner-sepolicy/product/private
|
||||||
|
|
||||||
|
The old `BOARD_PLAT_PUBLIC_SEPOLICY_DIR` and `BOARD_PLAT_PRIVATE_SEPOLICY_DIR`
|
||||||
|
variables have been deprecated in favour of `SYSTEM_EXT_*`.
|
||||||
|
|
||||||
|
Additionally, OEMs can specify `BOARD_SEPOLICY_M4DEFS` to pass arbitrary `m4`
|
||||||
|
definitions during the build. A definition consists of a string in the form
|
||||||
|
of `macro-name=value`. Spaces must **NOT** be present. This is useful for building modular
|
||||||
|
policies, policy generation, conditional file paths, etc. It is supported in
|
||||||
|
the following file types:
|
||||||
|
* All `*.te` and SELinux policy files as passed to `checkpolicy`
|
||||||
|
* `file_contexts`
|
||||||
|
* `service_contexts`
|
||||||
|
* `property_contexts`
|
||||||
|
* `keys.conf`
|
||||||
|
|
||||||
|
Example BoardConfig.mk Usage:
|
||||||
|
|
||||||
|
BOARD_SEPOLICY_M4DEFS += btmodule=foomatic \
|
||||||
|
btdevice=/dev/gps
|
||||||
|
|
||||||
|
## SPECIFIC POLICY FILE INFORMATION
|
||||||
|
|
||||||
|
### mac_permissions.xml
|
||||||
|
The `mac_permissions.xml` file is used for controlling the mmac solutions
|
||||||
|
as well as mapping a public base16 signing key with an arbitrary seinfo
|
||||||
|
string. Details of the files contents can be found in a comment at the
|
||||||
|
top of that file. The seinfo string, previously mentioned, is the same string
|
||||||
|
that is referenced in seapp_contexts.
|
||||||
|
|
||||||
|
It is important to note the final processed version of this file
|
||||||
|
is stripped of comments and whitespace. This is to preserve space on the
|
||||||
|
system.img. If one wishes to view it in a more human friendly format,
|
||||||
|
the `tidy` or `xmllint` command will assist you.
|
||||||
|
|
||||||
|
### insertkeys.py
|
||||||
|
Is a helper script for mapping arbitrary tags in the signature stanzas of
|
||||||
|
`mac_permissions.xml` to public keys found in pem files. This script takes
|
||||||
|
a `mac_permissions.xml` file(s) and configuration file in order to operate.
|
||||||
|
Details of the configuration file (`keys.conf`) can be found in the subsection
|
||||||
|
keys.conf. This tool is also responsible for stripping the comments and
|
||||||
|
whitespace during processing.
|
||||||
|
|
||||||
|
### keys.conf
|
||||||
|
The `keys.conf` file is used for controlling the mapping of "tags" found in
|
||||||
|
the `mac_permissions.xml` signature stanzas with actual public keys found in
|
||||||
|
pem files. The configuration file is processed via `m4`.
|
||||||
|
|
||||||
|
The script allows for mapping any string contained in `TARGET_BUILD_VARIANT`
|
||||||
|
with specific path to a pem file. Typically `TARGET_BUILD_VARIANT` is either
|
||||||
|
user, eng or userdebug. Additionally, one can specify "ALL" to map a path to
|
||||||
|
any string specified in `TARGET_BUILD_VARIANT`. All tags are matched verbatim
|
||||||
|
and all options are matched lowercase. The options are **tolowered** automatically
|
||||||
|
for the user, it is convention to specify tags and options in all uppercase
|
||||||
|
and tags start with @. The option arguments can also use environment variables
|
||||||
|
via the familiar `$VARIABLE` syntax. This is often useful for setting a location
|
||||||
|
to ones release keys.
|
||||||
|
|
||||||
|
Often times, one will need to integrate an application that was signed by a separate
|
||||||
|
organization and may need to extract the pem file for the `insertkeys/keys.conf` tools.
|
||||||
|
Extraction of the public key in the pem format is possible via `openssl`. First you need
|
||||||
|
to unzip the apk, once it is unzipped, `cd` into the `META_INF` directory and then execute
|
||||||
|
|
||||||
|
openssl pkcs7 -inform DER -in CERT.RSA -out CERT.pem -outform PEM -print_certs
|
||||||
|
|
||||||
|
On some occasions `CERT.RSA` has a different name, and you will need to adjust for that.
|
||||||
|
After extracting the pem, you can rename it, and configure `keys.conf` and
|
||||||
|
`mac_permissions.xml` to pick up the change. You **MUST** open the generated pem file in a text
|
||||||
|
editor and strip out anything outside the opening and closing scissor lines. Failure to do
|
||||||
|
so **WILL** cause a compile time issue thrown by insertkeys.py
|
||||||
|
|
||||||
|
**NOTE:** The pem files are base64 encoded and `PackageManagerService`, `mac_permissions.xml`
|
||||||
|
and `setool` all use base16 encodings.
|
||||||
Loading…
Reference in a new issue