xref: /docs/source.android.com/src/devices/tech/config/uicc.jd

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 &lt;= 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>