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
|
<!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="viewport" content="width=device-width, initial-scale=1"/>
<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="stylesheet" href="/grapheneos.css?5"/>
<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="/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">Usage</h1>
<p><strong>This guide is still very new and will be filled with lots of additional
content over time.</strong></p>
<h2 id="auditor">
Auditor
<a href="#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">
Updates
<a href="#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">
Settings
<a href="#updates-settings">¶</a>
</h3>
<p>The settings are available in the Settings app in System ➔ Advanced ➔ Update
settings.</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">
Security
<a href="#updates-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">
Disabling
<a href="#updates-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>
<h2 id="default-connections">
Default connections
<a href="#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://seamlessupdate.app/DEVICE-CHANNEL approximately once every four hours
when connected to a permitted network for updates.</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.</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>
</ul>
<p>Similar connectivity checks are also performed by the hardened Chromium browser (Vanadium).</p>
</div>
<footer>
<a href="/"><img src="https://grapheneos.org/logo.png" width="512" height="512" alt=""/>GrapheneOS</a>
<div id="social">
<a href="https://twitter.com/GrapheneOS">Twitter</a>
<a href="https://github.com/GrapheneOS">GitHub</a>
</div>
</footer>
</body>
</html>
|
