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
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
|
<!DOCTYPE html>
<html lang="en" prefix="og: http://ogp.me/ns#">
<head>
<meta charset="utf-8"/>
<title>Usage | GrapheneOS</title>
<meta name="description" content="Usage instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
<meta name="theme-color" content="#212121"/>
<meta name="msapplication-TileColor" content="#ffffff"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="twitter:site" content="@GrapheneOS"/>
<meta name="twitter:creator" content="@GrapheneOS"/>
<meta property="og:title" content="GrapheneOS usage documentation"/>
<meta property="og:description" content="Usage instructions for GrapheneOS, a security and privacy focused mobile OS with Android app compatibility."/>
<meta property="og:type" content="website"/>
<meta property="og:image" content="https://grapheneos.org/opengraph.png"/>
<meta property="og:image:width" content="512"/>
<meta property="og:image:height" content="512"/>
<meta property="og:image:alt" content="GrapheneOS logo"/>
<meta property="og:url" content="https://grapheneos.org/usage"/>
<meta property="og:site_name" content="GrapheneOS"/>
<link rel="icon" type="image/vnd.microsoft.icon" href="/favicon.ico"/>
<link rel="mask-icon" href="/mask-icon.svg" color="#1a1a1a"/>
<link rel="stylesheet" href="/grapheneos.css?13"/>
<link rel="manifest" href="/manifest.webmanifest"/>
<link rel="canonical" href="https://grapheneos.org/usage"/>
</head>
<body>
<nav>
<ul>
<li><a href="/">GrapheneOS</a></li>
<li><a href="/install">Install</a></li>
<li><a href="/build">Build</a></li>
<li class="active"><a href="/usage">Usage</a></li>
<!--<li><a href="/faq">FAQ</a></li>-->
<li><a href="/releases">Releases</a></li>
<li><a href="/source">Source</a></li>
<li><a href="/donate">Donate</a></li>
<li><a href="/contact">Contact</a></li>
</ul>
</nav>
<div id="content">
<h1 id="usage">
<a href="#usage">Usage</a>
</h1>
<p><strong>This guide is still very new and will be filled with lots of additional
content over time.</strong></p>
<h2 id="table-of-contents">
<a href="#table-of-contents">Table of contents</a>
</h2>
<ul>
<li><a href="#auditor">Auditor</a></li>
<li>
<a href="#updates">Updates</a>
<ul>
<li><a href="#updates-settings">Settings</a></li>
<li><a href="#updates-security">Security</a></li>
<li><a href="#updates-disabling">Disabling</a></li>
<li><a href="#updates-sideloading">Sideloading</a></li>
</ul>
</li>
<li><a href="#default-connections">Default connections</a></li>
<li><a href="#web-browsing">Web browsing</a></li>
<li><a href="#camera">Camera</a></li>
<li><a href="#exec-spawning">Exec spawning</a></li>
<li><a href="#bugs-uncovered-by-security-features">Bugs uncovered by security features</a></li>
</ul>
<h2 id="auditor">
<a href="#auditor">Auditor</a>
</h2>
<p>See the <a href="https://attestation.app/tutorial">tutorial page on the site for the attestation sub-project</a>.</p>
<h2 id="updates">
<a href="#updates">Updates</a>
</h2>
<p>The update system implements automatic background updates. It checks for updates
approximately once every four hours when there's network connectivity and then
downloads and installs updates in the background. It will pick up where it left off if
downloads are interrupted, so you don't need to worry about interrupting it.
Similarly, interrupting the installation isn't a risk because updates are installed to
a secondary installation of GrapheneOS which only becomes the active installation
after the update is complete. Once the update is complete, you'll be informed with a
notification and simply need to reboot with the button in the notification or via a
normal reboot. If the new version fails to boot, the OS will be rolled back to the
past version and the updater will attempt to download and install the update
again.</p>
<p>The updater will use incremental (delta) updates to download only changes rather
than the whole OS when one is available to go directly from the installed version to
the latest version. As long as you have working network connectivity on a regular
basis and reboot when asked, you'll almost always be on one of the past couple
versions of the OS which will minimize bandwidth usage since incrementals will always
be available.</p>
<p>The updater works while the device is locked / idle, including before the first
unlock since it's explicitly designed to be able to run before decryption of user
data.</p>
<p>Release changelogs are available <a href="/releases#changelog">in a section on the releases page</a>.</p>
<h3 id="updates-settings">
<a href="#updates-settings">Settings</a>
</h3>
<p>The settings are available in the Settings app in System ➔ Advanced ➔ Update
settings.</p>
<p>The "Check for updates" option will manually trigger an update check as soon as
possible. It will still wait for the configuration conditions listed below to be
satisfied, such as being connected to the internet via one of the permitted network
types.</p>
<p>The "Release channel" setting can be changed from the default Stable channel to the
Beta channel if you want to help with testing. The Beta channel will usually simply
follow the Stable channel, but the Beta channel may be used to experiment with new
features.</p>
<p>The "Permitted networks" setting controls which networks will be used to perform
updates. It defaults to using any network connection. It can be set to "Non-roaming"
to disable it when the cellular service is marked as roaming or "Unmetered" to disable
it on cellular networks and also Wi-Fi networks marked as metered.</p>
<p>The "Require battery above warning level" setting controls whether updates will
only be performed when the battery is above the level where the warning message is
shown. The standard value is at 15% capacity.</p>
<p>Enabling the opt-in "Automatic reboot" setting allows the updater to reboot the
device after an update once it has been idle for a long time. When this setting is
enabled, a device can take care of any number of updates completely automatically even
if it's left completely idle.</p>
<h3 id="updates-security">
<a href="#updates-security">Security</a>
</h3>
<p>The update server isn't a trusted party since updates are signed and verified along
with downgrade attacks being prevented. The update protocol doesn't send identifiable
information to the update server and works well over a VPN / Tor. GrapheneOS isn't
able to comply with a government order to build, sign and ship a malicious update to a
specific user's device based on information like the IMEI, serial number, etc. The
update server only ends up knowing the IP address used to connect to it and the
version being upgraded from based on the requested incremental.</p>
<p>Android updates can support serialno constraints to make them validate only on a
certain device but GrapheneOS rejects any update with a serialno constraint for both
the Stable and Beta channels.</p>
<h3 id="updates-disabling">
<a href="#updates-disabling">Disabling</a>
</h3>
<p>It's highly recommended to leave automatic updates enabled and to configure the
permitted networks if the bandwidth usage is a problem on your mobile data connection.
However, it's possible to turn off the update client by going to Settings ➔ Apps,
enabling Show system via the menu, selecting Seamless Update Client and disabling the
app. If you do this, you'll need to remember to enable it again to start receiving
updates.</p>
<h3 id="updates-sideloading">
<a href="#updates-sideloading">Sideloading</a>
</h3>
<p>Updates can be downloaded via
<a href="https://grapheneos.org/releases">the releases page</a> and installed via recovery
with adb sideloading. The zip files are signed and verified by recovery, just as they
are by the update client within the OS. This includes providing downgrade protection,
which prevents attempting to downgrade the version. If recovery didn't enforce these
things, they would still be enforced via verified boot including downgrade protection
on modern devices (Pixel 2 and later) and the attempted update would just fail to boot
and be rolled back.</p>
<p>To install one by sideloading, first, boot into recovery. You may do this either by
using <code>adb reboot recovery</code> from the operating system, or by selecting the
"Recovery" option in the bootloader menu.</p>
<p>You should see the green Android lying on its back being repaired, with the text "No
command" meaning that no command has been passed to recovery.</p>
<p>Next, access the recovery menu by holding down the power button and pressing the volume
up button a single time. This key combination toggles between the GUI and text-based mode
with the menu and log output.</p>
<p>Finally, select the "Apply update from ADB" option in the recovery menu and
sideload the update with adb. For example:</p>
<pre>adb sideload blueline-ota_update-2019.07.01.21.zip</pre>
<p><strong>You do not need to have adb enabled within the OS or the host's ADB key
whitelisted within the OS to sideload an update to recovery. Recovery mode does not
trust the attached computer and this can be considered a production feature. Trusting
a computer with ADB access within the OS is much different and exposes the device to a
huge amount of attack surface and control by the trusted computer.</strong></p>
<h2 id="default-connections">
<a href="#default-connections">Default connections</a>
</h2>
<p>GrapheneOS makes connections to the outside world to test connectivity, detect
captive portals and download updates. No data varying per user / installation is sent
in these connections. There aren't analytics / telemetry in GrapheneOS.</p>
<p>The expected default connections by GrapheneOS (including all base system apps) are
the following:</p>
<ul>
<li>
<p>The GrapheneOS Updater app fetches update metadata from
https://releases.grapheneos.org/DEVICE-CHANNEL approximately once every four hours
when connected to a permitted network for updates.</p>
<p>Once an update is available, it tries to download
https://releases.grapheneos.org/DEVICE-incremental-OLD_VERSION-NEW_VERSION.zip
for a delta update, and then falls back to
https://releases.grapheneos.org/DEVICE-ota_update-NEW_VERSION.zip.</p>
<p>No query / data is sent to the server, so the only information leaked to it
are the variables in these 3 URLs (device, channel, current version) which is
necessary to obtain the update.</p>
<p>Users can control which types of connections the Updater app will use, and
although it's strongly recommended to always leave it enabled it can be
disabled.</p>
</li>
<li>
<p>On devices with a Qualcomm baseband (which provides GPS), when location
functionality is being used,
<a href="https://en.wikipedia.org/wiki/GPS_signals#Almanac">GPS almanacs</a>
are downloaded from https://xtrapath1.izatcloud.net/xtra3grc.bin,
https://xtrapath2.izatcloud.net/xtra3grc.bin or
https://xtrapath3.izatcloud.net/xtra3grc.bin. GrapheneOS has modified all
references to these servers to use HTTPS rather than a mix of HTTP and HTTPS.
No query / data is sent to the server.</p>
</li>
<li>
<p>Connectivity checks designed to mimic a web browser user agent are performed
by using HTTP and HTTPS to fetch standard URLs generating an HTTP 204 status
code. This is used to detect when internet connectivity is lost on a network,
which triggers fallback to other available networks if possible. These checks
are designed to detect and handle captive portals which substitute the
expected empty 204 response with their own web page. These need use a very
common domain and URL in order to bypass whitelisting systems only permitting
access to common domains / URLs so a domain like grapheneos.org would likely
be inadequate. GrapheneOS leaves these set to the standard four URLs to blend
into the crowd of billions of other Android devices with and without Google
Mobile Services performing the same empty GET requests. For privacy reasons,
it isn't desirable to stand out from the crowd and changing these URLs or even
disabling the feature will likely reduce your privacy by giving your device a
more unique fingerprint. GrapheneOS aims to appear like any other common
mobile device on the network.</p>
<ul>
<li>HTTPS: https://www.google.com/generate_204</li>
<li>HTTP: http://connectivitycheck.gstatic.com/generate_204</li>
<li>HTTP fallback: http://www.google.com/gen_204</li>
<li>HTTP other fallback: http://play.googleapis.com/generate_204</li>
</ul>
<p>Standard AOSP user agent for the GET request:</p>
<p>Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.32 Safari/537.36</p>
<p>No query / data is sent and the response is unused beyond checking the response code.</p>
</li>
<li>
<p>DNS connectivity and functionality tests</p>
</li>
<li>
<p>DNS resolution for other connections</p>
</li>
<li>
<p>An HTTPS connection is made to https://time.grapheneos.org/ to update the
time from the date header field. This is a full replacement of Android's
standard network time update implementation, which uses the cellular network
when available with a fallback to SNTP when it's not available. This can be
disabled with the toggle at Settings ➔ System ➔ Date & time ➔ Use
network-provided time.</p>
</li>
</ul>
<p>Similar connectivity checks are also performed by the hardened Chromium browser (Vanadium).</p>
<h2 id="web-browsing">
<a href="#web-browsing">Web browsing</a>
</h2>
<p>GrapheneOS includes a Vanadium subproject providing privacy and security enhanced
releases of Chromium. Vanadium is both the user-facing browser included in the OS and
the provider of the WebView used by other apps to render web content. The WebView is
the browser engine used by the vast majority of web browsers and nearly all other apps
embedding web content or using web technologies for other uses.</p>
<p>Using Vanadium is highly recommended and Bromite is a good alternative if you want
a few more features like ad-blocking and more aggressive anti-fingerprinting. Vanadium
is working towards including these features and is actively collaborating with
Bromite. Standalone browsers based on Chromium have by far the best sandbox
implementation. Site isolation can also be enabled, which makes the sandbox enforce a
security boundary containing each site rather than isolating content as a whole.
Vanadium enables site isolation by default, and Bromite enables it on high memory
devices, including all officially supported GrapheneOS devices. Site isolation
prevents an attacker from obtaining cookies (like login sessions) and other data tied
to other sites if they successfully exploit the browser's rendering engine. It also
provides the strongest available mitigation for Spectre-based side channel
attacks.</p>
<p>WebView-based browsers use the hardened Vanadium rendering engine, but they can't
offer as much privacy and control due to being limited to the capabilities supported
by the WebView widget. For example, they can't provide a setting for toggling sensors
access because the feature is fairly new and the WebView WebSettings API doesn't yet
include support for it as it does for JavaScript, location, cookies, DOM storage and
other older features. For sensors, the Sensors app permission added by GrapheneOS can
be toggled off for the browser app as a whole instead. The WebView sandbox also
currently runs every instance within the same process and doesn't support site
isolation.</p>
<p>Avoid Gecko-based browsers like Firefox as they're currently much more vulnerable
to exploitation and inherently add a huge amount of attack surface. Gecko doesn't have
a WebView implementation (GeckoView is not a WebView implementation), so it has to be
used alongside the Chromium-based WebView rather than instead of Chromium, which means
having the remote attack surface of two separate browser engines instead of only one.
Firefox / Gecko also bypass or cripple a fair bit of the upstream and GrapheneOS
hardening work for apps. Worst of all, Firefox runs as a single process on mobile and
has no sandbox beyond the OS sandbox. This is despite the fact that Chromium semantic
sandbox layer on Android is implemented via the OS <code>isolatedProcess</code>
feature, which is a very easy to use boolean property for app service processes to
provide strong isolation with only the ability to communicate with the app running
them via the standard service API. Even in the desktop version, Firefox's sandbox is
still substantially weaker (especially on Linux, where it can hardly be considered a
sandbox at all) and lacks support for isolating sites from each other rather than only
containing content as a whole.</p>
<h2 id="camera">
<a href="#camera">Camera</a>
</h2>
<p>The Camera app included in GrapheneOS is very basic and can't take full advantage
of the hardware. It doesn't offer much in the way of configuration. In the long term,
it's going to be replaced. In the short term, there are other apps available providing
more capabilities and better support for taking advantage of the hardware.</p>
<p>The Pixel 2 and Pixel 3 (but not the Pixel 3a) have a Pixel Visual Core providing
a hardware-based implementation of HDR+. HDR+ captures many images and intelligently
merges data across them, taking into account motion, etc. It substantially improves
the quality of images, especially in low light. This is used transparently for third
party apps that are compatible with it, and there isn't an explicit switch to turn it
on or off for most of them. An example of a compatible app is Open Camera's default
configuration, or Open Camera with the Camera 2 API and other settings (including the
the various knobs / toggles outside of the settings menu) left alone. In general, HDR+
will work transparently in most apps as long as they keep things simple and use a good
minimalist approach to taking pictures. It should work transparently in most messaging
apps, etc. with internal support for taking pictures.</p>
<p>In addition to supporting HDR+ via the Pixel Visual Core, or similar features on
other devices with the same constraints, Open Camera offers advanced configuration and
various advanced features. Make sure to enable the Camera 2 API in the settings, which
should be the default, but the app doesn't have a great user interface / user
experience. You probably don't want to use the traditional HDR feature in the app.
That's not HDR+, but rather captures 3 images and merges them in a way that isn't at
all intelligent and causes a lot of blur and distortion. The HDR+ implementation can
actually benefit from the camera not being completely steady as it's smart enough to
match up the picture and it provides it with more data vs. a traditional HDR
implementation where it essentially doesn't work without a tripod and is not really at
all useful on a phone unless you actually have that for it.</p>
<h2 id="exec-spawning">
<a href="#exec-spawning">Exec spawning</a>
</h2>
<p>You may notice that cold start app spawning time takes a bit longer (i.e. in the
ballpark of 100ms) than stock Android, along with higher app memory usage. This is due
to security centric exec spawning model used by GrapheneOS to provide each application
with a unique address space layout, random hardened_malloc heap layout and unique keys
/ seeds for other probabilistic exploit mitigations like stack canaries, setjmp
protection and future features like randomized memory tags. Exec spawning doesn't
cause a performance cost after launching an app, and similarly doesn't cause any extra
latency for app spawning if the app was already running / cached in the background. It
isn't very noticeable on flagship devices with a high end CPU like a Pixel 3, and is a
lot more noticeable on a lower end device like a Pixel 3a.</p>
<h2 id="bugs-uncovered-by-security-features">
<a href="#bugs-uncovered-by-security-features">Bugs uncovered by security features</a>
</h2>
<p>GrapheneOS substantially expands the standard mitigations for memory corruption
vulnerabilities. Some of these features are designed to directly catch the memory
corruption bugs either via an explicit check or memory protection and abort the
program in order to prevent them from being exploited. Other features mitigate issues
a bit less directly such as zeroing data immediately upon free, isolated memory
regions, heap randomization, etc. and can also lead to latent memory corruption bugs
crashing instead of the program continuing onwards with corrupted memory. This means
that many latent memory corruption bugs in apps are caught along with some in the OS
itself. These bugs are not caused by GrapheneOS, but rather already existed and are
uncovered by the features. The features are aimed at preventing or hindering exploits,
not finding bugs, but they do that as part of doing their actual job.</p>
<p>Similarly, some of the other privacy and security improvements reduce the access
available to applications and they may crash. Some of these features are always
enabled under the hood, while others like the Network and Sensors toggles are
controlled by users via opt-in or opt-out toggles. Apps may not handle having access
taken away like this, although it generally doesn't cause any issues as it's all
designed to be friendly to apps and fully compatible rather than killing the
application when it violates the rules.</p>
<p>If you run into an application aborting, try to come up with a process for
reproducing the issue and then capture a bug report via the 'Take bug report' feature
in Developer options. Report an issue to the GrapheneOS OS issue tracker and email the
bug report capture zip to contact@grapheneos.org with the issue tracker number in the
subject like "Bug report capture for issue #104". The bug report capture includes
plain text 'tombstones' with logs, tracebacks, address space layout, register content
and a tiny bit of context from memory from areas that are interesting for debugging.
This may contain some sensitive data. Feel free to provide only the tombstone for the
relevant crash and filter out information you don't want to send. However, it will be
more difficult to debug if you provide less of the information. If the app doesn't
work with sensitive information, just send the whole tombstone.</p>
</div>
<footer>
<a href="/"><img src="https://grapheneos.org/logo.png" width="512" height="512" alt=""/>GrapheneOS</a>
<ul id="social">
<li><a href="https://twitter.com/GrapheneOS">Twitter</a></li>
<li><a href="https://github.com/GrapheneOS">GitHub</a></li>
<li><a href="https://reddit.com/r/GrapheneOS">Reddit</a></li>
</ul>
</footer>
</body>
</html>
|
