1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
<html devsite>
<head>
<title>Privileged Permission Whitelisting</title>
<meta name="project_path" value="/_project.yaml" />
<meta name="book_path" value="/_book.yaml" />
</head>
<body>
<!--
Copyright 2017 The Android Open Source Project
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<p>
Privileged applications are system applications located in the
<code>/system/priv-app</code> directory on the system image. Historically,
device implementers had little control over which signature|privileged
permissions could be granted to privileged apps. Starting in Android 8.0,
implementors can explicitly whitelist privileged apps in the system
configuration XML files in the <code>/etc/permissions</code> directory. Apps
not explicitly listed in these XML files are not granted privileged
permissions.
</p>
<h2 id="adding-whitelists">Adding whitelists</h2>
<p>
Permission whitelists for applications can be listed in a single or multiple
XML files located in the <code>frameworks/base/etc/permissions</code>
directory as follows:
</p>
<ul>
<li><code>/etc/permissions/privapp-permissions-<var>OEM_NAME</var>.xml</code>
<li><code>/etc/permissions/privapp-permissions-<var>DEVICE_NAME</var>.xml</code>
</ul>
<p>There is no strict rule for organizing content. Device implementers can
determine content structure as long as all applications from
<code>/system/priv-app</code> are whitelisted. For example, Google has a
single whitelist for all privileged applications developed by Google. We
recommend the following organization:
</p>
<ul>
<li>Permissions for apps that are already included in the Android Open Source
Project (AOSP) tree are listed in
<code>/etc/permissions/privapp-permissions-platform.xml</code>.</li>
<li>Permissions for Google applications are listed in
<code>/etc/permissions/privapp-permissions-google.xml</code>.</li>
<li>For other applications, use files of the form:
<code>/etc/permissions/privapp-permissions-<var>DEVICE_NAME</var>.xml</code>.
</li>
</ul>
<h3 id="generating-whitelists">Generating whitelists</h3>
<p>
To automatically generate a whitelist for all applications available on the
system image, use the AOSP command line tool at
<code>development/tools/privapp_permissions/privapp_permissions.py</code>. To
generate an initial version of device-specific
<code>privapp-permissions.xml</code>:
</p>
<ol>
<li>Build a system image:
<pre class="devsite-click-to-copy">
<code class="devsite-terminal">. build/envsetup.sh</code>
<code class="devsite-terminal">lunch <var>PRODUCT_NAME</var></code>
<code class="devsite-terminal">make -j</code></pre>
</li>
<li>Run the <code>privapp_permissions.py</code> script to generate a
<code>privapp-permissions.xml</code>file that lists all
signature|privileged permissions required to be whitelisted:
<pre class="devsite-terminal devsite-click-to-copy">development/tools/privapp_permissions/privapp_permissions.py</pre>
This tool prints XML content that can be used as a single file or split into
multiple files in <code>/etc/permissions</code>.
If the device already includes whitelists in the
<code>/etc/permissions</code> directory, the tool prints the differences
only (i.e. the missing signature|privileged permissions to be added to the
whitelist). This is also useful for audit purposes: When a new version of
the app is added, the tool detects the additional permissions needed.
</li>
<li>Copy the generated files to the <code>/etc/permissions</code> directory,
where the system will read those files during boot.</li>
</ol>
<h3 id="customizing-whitelists">Customizing whitelists</h3>
<p>
AOSP includes a whitelist implementation that can be customized as needed.
Permissions for apps included in AOSP are already whitelisted in
<code>/etc/permissions/privapp-permissions-platform.xml</code>.
</p>
<p>
By default, the <code>privapp_permissions.py</code> script generates output
that automatically grants any permission requested by a privileged
application. If there are permissions that should be denied, edit the XML to
use a "deny-permission" tag instead of a "permission" tag. Example:
</p>
<pre class="prettyprint"><!--
This XML file declares which signature|privileged permissions should be
granted to privileged applications that come with the platform
-->
<permissions>
<privapp-permissions package="com.android.backupconfirm">
<permission name="android.permission.BACKUP"/>
<permission name="android.permission.CRYPT_KEEPER"/>
</privapp-permissions>
<privapp-permissions package="com.android.cellbroadcastreceiver">
<!-- don't allow application to interact across users -->
<deny-permission name="android.permission.INTERACT_ACROSS_USERS"/>
<permission name="android.permission.MANAGE_USERS"/>
<permission name="android.permission.MODIFY_PHONE_STATE"/>
<permission name="android.permission.READ_PRIVILEGED_PHONE_STATE"/>
<permission name="android.permission.RECEIVE_EMERGENCY_BROADCAST"/>
</privapp-permissions>
...</pre>
<h3 id="finding-missing-permissions">Finding missing permissions</h3>
<p>
When bringing up a new device, find missing permissions by enabling
transitional log-mode:
</p>
<pre class="devsite-click-to-copy">ro.control_privapp_permissions=log</pre>
<p>
Violations are reported in the log file, but permissions are still granted.
This keeps the device in a working state while providing the list of
violations. The error message format is as follows:
</p>
<pre class="devsite-click-to-copy">
PackageManager: Privileged permission {PERMISSION_NAME} for package {PACKAGE_NAME} - not in privapp-permissions whitelist
</pre>
<p>
All violations must be addressed by adding the apps to whitelists. If not
added, the apps will not be granted the missing permissions even if they are
in the priv-app path.
</p>
<h2 id="enforcing-whitelists">Enforcing whitelists</h2>
<p>
After whitelists are in place, enable runtime enforcement by setting the build
property <code>ro.control_privapp_permissions=enforce</code>.
</p>
<aside class="note"><strong>Note:</strong> The
<code>ro.control_privapp_permissions</code> property state must adhere to
<a href="/compatibility/android-cdd#9_1_permissions">CDD section 9.1
requirements</a>.</aside>
</body>
</html>
|
