README
1 Policy Generation:
2
3 Additional, per device, policy files can be added into the
4 policy build.
5
6 They can be configured through the use of three variables,
7 they are:
8 1. BOARD_SEPOLICY_REPLACE
9 2. BOARD_SEPOLICY_UNION
10 3. BOARD_SEPOLICY_DIRS
11 4. BOARD_SEPOLICY_IGNORE
12
13 The variables should be set in the BoardConfig.mk file in
14 the device or vendor directories.
15
16 BOARD_SEPOLICY_UNION is a list of files that will be
17 "unioned", IE concatenated, at the END of their respective
18 file in external/sepolicy. Note, to add a unique file you
19 would use this variable.
20
21 BOARD_SEPOLICY_REPLACE is a list of files that will be
22 used instead of the corresponding file in external/sepolicy.
23
24 BOARD_SEPOLICY_DIRS contains a list of directories to search
25 for BOARD_SEPOLICY_UNION and BOARD_SEPOLICY_REPLACE files. Order
26 matters in this list.
27 eg.) If you have BOARD_SEPOLICY_UNION := widget.te and have 2
28 instances of widget.te files on BOARD_SEPOLICY_DIRS search path.
29 The first one found (at the first search dir containing the file)
30 gets processed first.
31 Reviewing out/target/product/<device>/etc/sepolicy_intermediates/policy.conf
32 will help sort out ordering issues.
33
34 It is an error to specify a BOARD_POLICY_REPLACE file that does
35 not exist in external/sepolicy.
36
37 It is an error to specify a BOARD_POLICY_REPLACE file that appears
38 multiple times on the policy search path defined by BOARD_SEPOLICY_DIRS.
39 eg.) if you specify shell.te in BOARD_SEPOLICY_REPLACE and
40 BOARD_SEPOLICY_DIRS is set to
41 "vendor/widget/common/sepolicy device/widget/x/sepolicy" and shell.te
42 appears in both locations, it is an error. Unless it is in
43 BOARD_SEPOLICY_IGNORE to be filtered out. See BOARD_SEPOLICY_IGNORE
44 for more details.
45
46 It is an error to specify the same file name in both
47 BOARD_POLICY_REPLACE and BOARD_POLICY_UNION.
48
49 It is an error to specify a BOARD_SEPOLICY_DIRS that has no entries when
50 specifying BOARD_SEPOLICY_REPLACE.
51
52 BOARD_SEPOLICY_IGNORE is a list of paths (directory + filename) of
53 files that are not to be included in the resulting policy. This list
54 is passed to filter-out to remove any paths you may want to ignore. This
55 is useful if you have numerous config directories that contain a file
56 and you want to NOT include a particular file in your resulting
57 policy file, either by UNION or REPLACE.
58 Eg.) Suppose the following:
59 BOARD_SEPOLICY_DIRS := X Y
60 BOARD_SEPOLICY_REPLACE := A
61 BOARD_SEPOLICY_IGNORE := X/A
62
63 Directories X and Y contain A.
64
65 The resulting policy is created by using Y/A only, thus X/A was
66 ignored.
67
68 Example BoardConfig.mk Usage:
69 From the Tuna device BoardConfig.mk, device/samsung/tuna/BoardConfig.mk
70
71 BOARD_SEPOLICY_DIRS := \
72 device/samsung/tuna/sepolicy
73
74 BOARD_SEPOLICY_UNION := \
75 genfs_contexts \
76 file_contexts \
77 sepolicy.te
78
79 SPECIFIC POLICY FILE INFORMATION
80
81 mac_permissions.xml:
82 ABOUT:
83 The mac_permissions.xml file is used for controlling the mmac solutions
84 as well as mapping a public base16 signing key with an arbitrary seinfo
85 string. Details of the files contents can be found in a comment at the
86 top of that file. The seinfo string, previously mentioned, is the same string
87 that is referenced in seapp_contexts.
88
89 This file can be replaced through BOARD_SEPOLICY_REPLACE containing the
90 value "mac_permissions.xml", or appended to by using the BOARD_SEPOLICY_UNION
91 variable. It is important to note the final processed version of this file
92 is stripped of comments and whitespace. This is to preserve space on the
93 system.img. If one wishes to view it in a more human friendly format,
94 the "tidy" or "xmllint" command will assist you.
95
96 TOOLING:
97 insertkeys.py
98 Is a helper script for mapping arbitrary tags in the signature stanzas of
99 mac_permissions.xml to public keys found in pem files. This script takes
100 a mac_permissions.xml file(s) and configuration file in order to operate.
101 Details of the configuration file (keys.conf) can be found in the subsection
102 keys.conf. This tool is also responsible for stripping the comments and
103 whitespace during processing.
104
105 keys.conf
106 The keys.conf file is used for controlling the mapping of "tags" found in
107 the mac_permissions.xml signature stanzas with actual public keys found in
108 pem files. The configuration file can be used in BOARD_SEPOLICY_UNION and
109 BOARD_SEPOLICY_REPLACE variables and is processed via m4.
110
111 The script allows for mapping any string contained in TARGET_BUILD_VARIANT
112 with specific path to a pem file. Typically TARGET_BUILD_VARIANT is either
113 user, eng or userdebug. Additionally, one can specify "ALL" to map a path to
114 any string specified in TARGET_BUILD_VARIANT. All tags are matched verbatim
115 and all options are matched lowercase. The options are "tolowered" automatically
116 for the user, it is convention to specify tags and options in all uppercase
117 and tags start with @.
118
119 NOTE: The pem files are base64 encoded and PackageManagerService, mac_permissions.xml
120 and setool all use base16 encodings.
121