| page.title=UICC Carrier Privileges |
| @jd:body |
| |
| <!-- |
| Copyright 2015 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. |
| --> |
| <div id="qv-wrapper"> |
| <div id="qv"> |
| <h2>In this document</h2> |
| <ol id="auto-toc"> |
| </ol> |
| </div> |
| </div> |
| |
| <p>Android 5.1 introduced a new mechanism to grant special privileges for APIs relevant |
| to the Universal Integrated Circuit Card (UICC) owner’s apps. The Android platform will load |
| certificates stored on a UICC and grant |
| permission to apps signed by these certificates to make calls to a handful of |
| special APIs. Since carriers have full control of the UICC, this mechanism |
| provides a secure and flexible way to manage apps from the Mobile Network |
| Operator (MNO) hosted on generic application distribution channels such as |
| Google Play but still have special privileges on devices without the need for |
| the apps to be signed by the per-device platform certificate or be |
| pre-installed as a system app.</p> |
| |
| <h2 id=rules_on_uicc>Rules on UICC</h2> |
| |
| <p>Storage on the UICC is compatible with the <a |
| href="http://www.globalplatform.org/specificationsdevice.asp">GlobalPlatform |
| Secure Element Access Control specification</a>. The application identifier |
| (AID) on card is A00000015141434C00, and the standard GET DATA command is used |
| to fetch rules stored on the card. You may update these rules via card |
| over-the-air (OTA) update. Data hierarchy is as follows (noting the |
| two-character letter and number combination in parentheses is the object tag). |
| (An extension to spec is under review.)</p> |
| |
| <p>Each rule is a REF-AR-DO (E2) and consists of a concatenation of a REF-DO and |
| an AR-DO:</p> |
| |
| <ul> |
| <li>REF-DO (E1) contains a DeviceAppID-REF-DO or a concatenation of a |
| DeviceAppID-REF-DO and a PKG-REF-DO. |
| <ul> |
| <li>DeviceAppID-REF-DO (C1) stores the SHA1 (20 bytes) or SHA256 (32 bytes) |
| signature of the certificate. |
| <li>PKG-REF-DO (CA) is the full package name string defined in manifest, ASCII |
| encoded, max length 127 bytes. |
| </ul> |
| <li>AR-DO (E3) is extended to include PERM-AR-DO (DB), which is an 8-byte bit mask |
| representing 64 separate permissions. |
| </ul> |
| |
| <p>If PKG-REF-DO is not present, any app signed by the certificate will be granted |
| access; otherwise both certificate and package name need to match.</p> |
| |
| <h3 id=example>Example</h3> |
| |
| <p>App name: com.google.android.apps.myapp<br> |
| Sha1 of certificate in hex string:</p> |
| <pre> |
| AB:CD:92:CB:B1:56:B2:80:FA:4E:14:29:A6:EC:EE:B6:E5:C1:BF:E4</pre> |
| |
| <p>Rule on UICC in hex string:</p> |
| <pre> |
| E243 <= 43 is value length in hex |
| E135 |
| C114 ABCD92CBB156B280FA4E1429A6ECEEB6E5C1BFE4 |
| CA1D 636F6D2E676F6F676C652E616E64726F69642E617070732E6D79617070 |
| E30A |
| DB08 0000000000000001 |
| </pre> |
| |
| <h2 id=enabled_apis>Enabled APIs</h2> |
| |
| <p>Currently we support the following APIs, listed below (refer to |
| developer.android.com for more details).</p> |
| |
| <h3 id=telephonymanager>TelephonyManager</h3> |
| |
| <p>API to check whether calling application has been granted carrier privileges:</p> |
| |
| <pre> |
| <a |
| href="http://developer.android.com/reference/android/telephony/TelephonyManager.html#hasCarrierPrivileges()">hasCarrierPrivileges</a> |
| </pre> |
| |
| <p>APIs for brand and number override:</p> |
| |
| <pre> |
| setOperatorBrandOverride |
| setLine1NumberForDisplay |
| setVoiceMailNumber |
| </pre> |
| |
| <p>APIs for direct UICC communication:</p> |
| |
| <pre> |
| iccOpenLogicalChannel |
| iccCloseLogicalChannel |
| iccExchangeSimIO |
| iccTransmitApduLogicalChannel |
| iccTransmitApduBasicChannel |
| sendEnvelopeWithStatus |
| </pre> |
| |
| <p>API to set device mode to global:</p> |
| |
| <pre> |
| setPreferredNetworkTypeToGlobal |
| </pre> |
| |
| <h3 id=smsmanager>SmsManager</h3> |
| |
| <p>API allows caller to create new incoming SMS messages:</p> |
| |
| <pre> |
| injectSmsPdu |
| </pre> |
| |
| <h4 id=carriermessagingservice>CarrierMessagingService</h4> |
| |
| <p>A service that receives calls from the system when new SMS and MMS are |
| sent or |
| received. To extend this class, you must declare the service in your manifest |
| file with the android.Manifest.permission#BIND_CARRIER_MESSAGING_SERVICE |
| permission and include an intent filter with the #SERVICE_INTERFACE action.</p> |
| |
| <pre> |
| onFilterSms |
| onSendTextSms |
| onSendDataSms |
| onSendMultipartTextSms |
| onSendMms |
| onDownloadMms |
| </pre> |
| |
| <h4 id=telephonyprovider>TelephonyProvider</h4> |
| |
| <p>Content provider APIs that allow modification to the telephony database, value |
| fields are defined at Telephony.Carriers:</p> |
| |
| <pre> |
| insert, delete, update, query |
| </pre> |
| |
| <p>See the <a |
| href="https://developer.android.com/reference/android/provider/Telephony.html">Telephony |
| reference on developer.android.com</a> for additional information.</p> |
| |
| <h2 id=android_platform>Android platform</h2> |
| |
| <p>On a detected UICC, the platform will construct internal UICC objects that |
| include carrier privilege rules as part of the UICC. <a |
| href="https://android.googlesource.com/platform/frameworks/opt/telephony/+/master/src/java/com/android/internal/telephony/uicc/UiccCarrierPrivilegeRules.java">UiccCarrierPrivilegeRules.java</a> |
| will load rules, parse them from the UICC card, and cache them in memory. When |
| a privilege check is needed, UiccCarrierPrivilegeRules will compare the caller |
| certificate with its own rules one by one. If the UICC is removed, rules will |
| be destroyed along with the UICC object.</p> |
| |
| <h2 id=faq>FAQ</h2> |
| |
| <p><strong>How can certificates be updated on the UICC? |
| </strong></p> |
| |
| <p><em>A: Use existing card OTA update mechanism. |
| </em></p> |
| |
| <p><strong>Can it co-exist with other rules? |
| </strong></p> |
| |
| <p><em>A: It’s fine to have other security rules on the UICC under same AID; the |
| platform will filter them out automatically. |
| </em></p> |
| |
| <p><strong>What happens when the UICC is removed for an app that relies on the |
| certificates on it? |
| </strong></p> |
| |
| <p><em>A: The app will lose its privileges because the rules associated with the UICC |
| are destroyed on UICC removal. |
| </em></p> |
| |
| <p><strong>Is there a limit on the number of certificates on the UICC? |
| </strong></p> |
| |
| <p><em>A: The platform doesn’t limit the number of certificates; but because the check |
| is linear, too many rules may incur a latency for check. |
| </em></p> |
| |
| <p><strong>Is there a limit to number of APIs we can support via this method? |
| </strong></p> |
| |
| <p><em>A: No, but we limit the scope of APIs to carrier related. |
| </em></p> |
| |
| <p><strong>Are there some APIs prohibited from using this method? If so, how do you |
| enforce them? (ie. Will you have tests to validate which APIs are supported via |
| this method?) |
| </strong></p> |
| |
| <p><em>A: Please refer to the "API Behavioral Compatibility" section of the <a |
| href="{@docRoot}compatibility/android-cdd.pdf">Android Compatibility Definition |
| Document CDD)</a>. We have some CTS tests to make sure the permission model of |
| the APIs is not changed. |
| </em></p> |
| |
| <p><strong>How does this work with the multi-SIM feature? |
| </strong></p> |
| |
| <p><em>A: The default SIM that gets set by the user will be used.</em></p> |
| |
| <p><strong>Does this in any way interact or overlap with other SE access technologies e.g. |
| SEEK? |
| <em>A: As an example, SEEK uses the same AID as on the UICC. So the rules co-exist |
| and are filtered by either SEEK or UiccCarrierPrivileges.</em> |
| </strong></p> |
| |
| <p><strong>When is it a good time to check carrier privileges? |
| <em>A: After the SIM state loaded broadcast.</em> |
| </strong></p> |
| |
| <p><strong>Can OEMs disable part of carrier APIs? |
| </strong></p> |
| |
| <p><em>A: No. We believe current APIs are the minimal set, and we plan to use the bit |
| mask for finer granularity control in the future. |
| </em></p> |
| |
| <p><strong>Does setOperatorBrandOverride override ALL other forms of operator name |
| strings? For example, SE13, UICC SPN, network based NITZ, etc.? |
| </strong></p> |
| |
| <p><em>A: See the SPN entry within TelephonyManager: |
| <a |
| href="http://developer.android.com/reference/android/telephony/TelephonyManager.html">http://developer.android.com/reference/android/telephony/TelephonyManager.html</a> |
| </em></p> |
| |
| <p><strong>What does the injectSmsPdu method call do? |
| </strong></p> |
| |
| <p><em>A: This facilitates SMS backup/restore in the cloud. The injectSmsPdu call |
| enables the restore function. |
| </em></p> |
| |
| <p><strong>For SMS filtering, is the onFilterSms call based on SMS UDH port filtering? Or |
| would carrier apps have access to ALL incoming SMS? |
| </strong></p> |
| |
| <p><em>A: Carriers have access to all SMS data.</em></p> |
| |
| <p><strong>Since the extension of DeviceAppID-REF-DO to support 32 bytes appears |
| incompatible with the current GP spec (which allows 0 or 20 bytes only) why are |
| you introducing this change? Do you not consider SHA-1 to be good enough to |
| avoid collisions? Have you proposed this change to GP already, as this could |
| be backwards incompatible with existing ARA-M / ARF? |
| </strong></p> |
| |
| <p><em>A: For providing future proof security this extension introduces SHA-256 for |
| DeviceAppID-REF-DO in addition to SHA-1 which is currently the only option in |
| the GP SEAC standard. It is highly recommended to use SHA-256.</em></p> |
| |
| <p><strong>If DeviceAppID is 0 (empty), would you really apply the rule to all device |
| applications not covered by a specific rule? |
| </strong></p> |
| |
| <p><em>A: Carrier apis require deviceappid-ref-do be non-empty. Being empty is |
| intended for test purpose and is not recommended for operational deployments.</em></p> |
| |
| <p><strong>According to your spec, PKG-REF-DO used just by itself, without |
| DeviceAppID-REF-DO, should not be accepted. But it is still described in Table |
| 6-4 as extending the definition of REF-DO. Is this on purpose? What will be the |
| behavior of the code when only a PKG-REF-DO is used in a REF-DO? |
| </strong></p> |
| |
| <p><em>A: The option of having PKG-REF-DO as a single value item in REF-DO was removed |
| in the latest version. PKG-REF-DO should only occur in combination with |
| DeviceAppID-REF-DO. |
| </em></p> |
| |
| <p><strong>We assume we can grant access to all carrier-based permissions or have a |
| finer-grained control. What will define the mapping between the bit mask and |
| the actual permissions then? One permission per class? One permission per |
| method specifically? Will 64 separate permissions be enough in the long run? |
| </strong></p> |
| |
| <p><em>A: This is reserved for the future, and we welcome suggestions.</em></p> |
| |
| <p><strong>Can you further define the DeviceAppID for Android specifically? Since this is |
| the SHA-1 (20 bytes) hash value of the Publisher certificate used to signed the |
| given app, shouldn't the name reflect that purpose? (The name could be |
| confusing to many readers as the rule will be applicable then to all apps |
| signed with that same Publisher certificate.) |
| </strong></p> |
| |
| <p><em>A: See the <a |
| href="#rules_on_uicc">Rules on UICC</a> section for details. The deviceAppID storing |
| certificates is already supported by the existing spec. We tried to minimize |
| spec changes to lower barrier for adoption. </em></p> |