1 page.title=UICC Carrier Privileges 2 @jd:body 3 4 <!-- 5 Copyright 2015 The Android Open Source Project 6 7 Licensed under the Apache License, Version 2.0 (the "License"); 8 you may not use this file except in compliance with the License. 9 You may obtain a copy of the License at 10 11 http://www.apache.org/licenses/LICENSE-2.0 12 13 Unless required by applicable law or agreed to in writing, software 14 distributed under the License is distributed on an "AS IS" BASIS, 15 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 See the License for the specific language governing permissions and 17 limitations under the License. 18 --> 19 <div id="qv-wrapper"> 20 <div id="qv"> 21 <h2>In this document</h2> 22 <ol id="auto-toc"> 23 </ol> 24 </div> 25 </div> 26 27 <p>Android 5.1 introduced a new mechanism to grant special privileges for APIs relevant 28 to the Universal Integrated Circuit Card (UICC) owners apps. The Android platform will load 29 certificates stored on a UICC and grant 30 permission to apps signed by these certificates to make calls to a handful of 31 special APIs. Since carriers have full control of the UICC, this mechanism 32 provides a secure and flexible way to manage apps from the Mobile Network 33 Operator (MNO) hosted on generic application distribution channels such as 34 Google Play but still have special privileges on devices without the need for 35 the apps to be signed by the per-device platform certificate or be 36 pre-installed as a system app.</p> 37 38 <h2 id=rules_on_uicc>Rules on UICC</h2> 39 40 <p>Storage on the UICC is compatible with the <a 41 href="http://www.globalplatform.org/specificationsdevice.asp">GlobalPlatform 42 Secure Element Access Control specification</a>. The application identifier 43 (AID) on card is A00000015141434C00, and the standard GET DATA command is used 44 to fetch rules stored on the card. You may update these rules via card 45 over-the-air (OTA) update. Data hierarchy is as follows (noting the 46 two-character letter and number combination in parentheses is the object tag). 47 (An extension to spec is under review.)</p> 48 49 <p>Each rule is a REF-AR-DO (E2) and consists of a concatenation of a REF-DO and 50 an AR-DO:</p> 51 52 <ul> 53 <li>REF-DO (E1) contains a DeviceAppID-REF-DO or a concatenation of a 54 DeviceAppID-REF-DO and a PKG-REF-DO. 55 <ul> 56 <li>DeviceAppID-REF-DO (C1) stores the SHA1 (20 bytes) or SHA256 (32 bytes) 57 signature of the certificate. 58 <li>PKG-REF-DO (CA) is the full package name string defined in manifest, ASCII 59 encoded, max length 127 bytes. 60 </ul> 61 <li>AR-DO (E3) is extended to include PERM-AR-DO (DB), which is an 8-byte bit mask 62 representing 64 separate permissions. 63 </ul> 64 65 <p>If PKG-REF-DO is not present, any app signed by the certificate will be granted 66 access; otherwise both certificate and package name need to match.</p> 67 68 <h3 id=example>Example</h3> 69 70 <p>App name: com.google.android.apps.myapp<br> 71 Sha1 of certificate in hex string:</p> 72 <pre> 73 AB:CD:92:CB:B1:56:B2:80:FA:4E:14:29:A6:EC:EE:B6:E5:C1:BF:E4</pre> 74 75 <p>Rule on UICC in hex string:</p> 76 <pre> 77 E243 <= 43 is value length in hex 78 E135 79 C114 ABCD92CBB156B280FA4E1429A6ECEEB6E5C1BFE4 80 CA1D 636F6D2E676F6F676C652E616E64726F69642E617070732E6D79617070 81 E30A 82 DB08 0000000000000001 83 </pre> 84 85 <h2 id=enabled_apis>Enabled APIs</h2> 86 87 <p>Currently we support the following APIs, listed below (refer to 88 developer.android.com for more details).</p> 89 90 <h3 id=telephonymanager>TelephonyManager</h3> 91 92 <p>API to check whether calling application has been granted carrier privileges:</p> 93 94 <pre> 95 <a 96 href="http://developer.android.com/reference/android/telephony/TelephonyManager.html#hasCarrierPrivileges()">hasCarrierPrivileges</a> 97 </pre> 98 99 <p>APIs for brand and number override:</p> 100 101 <pre> 102 setOperatorBrandOverride 103 setLine1NumberForDisplay 104 setVoiceMailNumber 105 </pre> 106 107 <p>APIs for direct UICC communication:</p> 108 109 <pre> 110 iccOpenLogicalChannel 111 iccCloseLogicalChannel 112 iccExchangeSimIO 113 iccTransmitApduLogicalChannel 114 iccTransmitApduBasicChannel 115 sendEnvelopeWithStatus 116 </pre> 117 118 <p>API to set device mode to global:</p> 119 120 <pre> 121 setPreferredNetworkTypeToGlobal 122 </pre> 123 124 <h3 id=smsmanager>SmsManager</h3> 125 126 <p>API allows caller to create new incoming SMS messages:</p> 127 128 <pre> 129 injectSmsPdu 130 </pre> 131 132 <h4 id=carriermessagingservice>CarrierMessagingService</h4> 133 134 <p>A service that receives calls from the system when new SMS and MMS are 135 sent or 136 received. To extend this class, you must declare the service in your manifest 137 file with the android.Manifest.permission#BIND_CARRIER_MESSAGING_SERVICE 138 permission and include an intent filter with the #SERVICE_INTERFACE action.</p> 139 140 <pre> 141 onFilterSms 142 onSendTextSms 143 onSendDataSms 144 onSendMultipartTextSms 145 onSendMms 146 onDownloadMms 147 </pre> 148 149 <h4 id=telephonyprovider>TelephonyProvider</h4> 150 151 <p>Content provider APIs that allow modification to the telephony database, value 152 fields are defined at Telephony.Carriers:</p> 153 154 <pre> 155 insert, delete, update, query 156 </pre> 157 158 <p>See the <a 159 href="https://developer.android.com/reference/android/provider/Telephony.html">Telephony 160 reference on developer.android.com</a> for additional information.</p> 161 162 <h2 id=android_platform>Android platform</h2> 163 164 <p>On a detected UICC, the platform will construct internal UICC objects that 165 include carrier privilege rules as part of the UICC. <a 166 href="https://android.googlesource.com/platform/frameworks/opt/telephony/+/master/src/java/com/android/internal/telephony/uicc/UiccCarrierPrivilegeRules.java">UiccCarrierPrivilegeRules.java</a> 167 will load rules, parse them from the UICC card, and cache them in memory. When 168 a privilege check is needed, UiccCarrierPrivilegeRules will compare the caller 169 certificate with its own rules one by one. If the UICC is removed, rules will 170 be destroyed along with the UICC object.</p> 171 172 <h2 id=faq>FAQ</h2> 173 174 <p><strong>How can certificates be updated on the UICC? 175 </strong></p> 176 177 <p><em>A: Use existing card OTA update mechanism. 178 </em></p> 179 180 <p><strong>Can it co-exist with other rules? 181 </strong></p> 182 183 <p><em>A: Its fine to have other security rules on the UICC under same AID; the 184 platform will filter them out automatically. 185 </em></p> 186 187 <p><strong>What happens when the UICC is removed for an app that relies on the 188 certificates on it? 189 </strong></p> 190 191 <p><em>A: The app will lose its privileges because the rules associated with the UICC 192 are destroyed on UICC removal. 193 </em></p> 194 195 <p><strong>Is there a limit on the number of certificates on the UICC? 196 </strong></p> 197 198 <p><em>A: The platform doesnt limit the number of certificates; but because the check 199 is linear, too many rules may incur a latency for check. 200 </em></p> 201 202 <p><strong>Is there a limit to number of APIs we can support via this method? 203 </strong></p> 204 205 <p><em>A: No, but we limit the scope of APIs to carrier related. 206 </em></p> 207 208 <p><strong>Are there some APIs prohibited from using this method? If so, how do you 209 enforce them? (ie. Will you have tests to validate which APIs are supported via 210 this method?) 211 </strong></p> 212 213 <p><em>A: Please refer to the "API Behavioral Compatibility" section of the <a 214 href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition 215 Document CDD)</a>. We have some CTS tests to make sure the permission model of 216 the APIs is not changed. 217 </em></p> 218 219 <p><strong>How does this work with the multi-SIM feature? 220 </strong></p> 221 222 <p><em>A: The default SIM that gets set by the user will be used.</em></p> 223 224 <p><strong>Does this in any way interact or overlap with other SE access technologies e.g. 225 SEEK? 226 <em>A: As an example, SEEK uses the same AID as on the UICC. So the rules co-exist 227 and are filtered by either SEEK or UiccCarrierPrivileges.</em> 228 </strong></p> 229 230 <p><strong>When is it a good time to check carrier privileges? 231 <em>A: After the SIM state loaded broadcast.</em> 232 </strong></p> 233 234 <p><strong>Can OEMs disable part of carrier APIs? 235 </strong></p> 236 237 <p><em>A: No. We believe current APIs are the minimal set, and we plan to use the bit 238 mask for finer granularity control in the future. 239 </em></p> 240 241 <p><strong>Does setOperatorBrandOverride override ALL other forms of operator name 242 strings? For example, SE13, UICC SPN, network based NITZ, etc.? 243 </strong></p> 244 245 <p><em>A: See the SPN entry within TelephonyManager: 246 <a 247 href="http://developer.android.com/reference/android/telephony/TelephonyManager.html">http://developer.android.com/reference/android/telephony/TelephonyManager.html</a> 248 </em></p> 249 250 <p><strong>What does the injectSmsPdu method call do? 251 </strong></p> 252 253 <p><em>A: This facilitates SMS backup/restore in the cloud. The injectSmsPdu call 254 enables the restore function. 255 </em></p> 256 257 <p><strong>For SMS filtering, is the onFilterSms call based on SMS UDH port filtering? Or 258 would carrier apps have access to ALL incoming SMS? 259 </strong></p> 260 261 <p><em>A: Carriers have access to all SMS data.</em></p> 262 263 <p><strong>Since the extension of DeviceAppID-REF-DO to support 32 bytes appears 264 incompatible with the current GP spec (which allows 0 or 20 bytes only) why are 265 you introducing this change? Do you not consider SHA-1 to be good enough to 266 avoid collisions? Have you proposed this change to GP already, as this could 267 be backwards incompatible with existing ARA-M / ARF? 268 </strong></p> 269 270 <p><em>A: For providing future proof security this extension introduces SHA-256 for 271 DeviceAppID-REF-DO in addition to SHA-1 which is currently the only option in 272 the GP SEAC standard. It is highly recommended to use SHA-256.</em></p> 273 274 <p><strong>If DeviceAppID is 0 (empty), would you really apply the rule to all device 275 applications not covered by a specific rule? 276 </strong></p> 277 278 <p><em>A: Carrier apis require deviceappid-ref-do be non-empty. Being empty is 279 intended for test purpose and is not recommended for operational deployments.</em></p> 280 281 <p><strong>According to your spec, PKG-REF-DO used just by itself, without 282 DeviceAppID-REF-DO, should not be accepted. But it is still described in Table 283 6-4 as extending the definition of REF-DO. Is this on purpose? What will be the 284 behavior of the code when only a PKG-REF-DO is used in a REF-DO? 285 </strong></p> 286 287 <p><em>A: The option of having PKG-REF-DO as a single value item in REF-DO was removed 288 in the latest version. PKG-REF-DO should only occur in combination with 289 DeviceAppID-REF-DO. 290 </em></p> 291 292 <p><strong>We assume we can grant access to all carrier-based permissions or have a 293 finer-grained control. What will define the mapping between the bit mask and 294 the actual permissions then? One permission per class? One permission per 295 method specifically? Will 64 separate permissions be enough in the long run? 296 </strong></p> 297 298 <p><em>A: This is reserved for the future, and we welcome suggestions.</em></p> 299 300 <p><strong>Can you further define the DeviceAppID for Android specifically? Since this is 301 the SHA-1 (20 bytes) hash value of the Publisher certificate used to signed the 302 given app, shouldn't the name reflect that purpose? (The name could be 303 confusing to many readers as the rule will be applicable then to all apps 304 signed with that same Publisher certificate.) 305 </strong></p> 306 307 <p><em>A: See the <a 308 href="#rules_on_uicc">Rules on UICC</a> section for details. The deviceAppID storing 309 certificates is already supported by the existing spec. We tried to minimize 310 spec changes to lower barrier for adoption. </em></p> 311
