tech/config/uicc.html

<html devsite>
  <head>
    <title>UICC Carrier Privileges</title>
    <meta name="project_path" value="/_project.yaml" />
    <meta name="book_path" value="/_book.yaml" />
  </head>
  <body>
  <!--
      Copyright 2017 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.
  -->


<p>Android 5.1 introduced a mechanism to grant special privileges for APIs
relevant to the Universal Integrated Circuit Card (UICC) owners apps. The
Android platform loads certificates stored on a UICC and grants permission to
apps signed by these certificates to make calls to a handful of special APIs.
</p>
<p>Android 7.0 extends this feature to support other storage sources, such as
Access File Rule (ARF), for UICC carrier privilege rules, dramatically
increasing the number of carriers that can use the APIs. For an API reference,
see <a href="#carrierconfigmanager">CarrierConfigManager</a>; for instructions,
see <a href="/devices/tech/config/carrier.html">Carrier
Configuration</a>.</p>

<p>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) while
retaining special privileges on devices and without the need to sign apps with
the per-device platform certificate or pre-install 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 <code>A00000015141434C00</code>, 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.</p>

<h3 id=data_hierarchy>Data hierarchy</h3>
<p>UICC rules use the following data hierarchy (the two-character letter and
number combination in parentheses is the object tag). 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 SHA-1 (20 bytes) or SHA-256 (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>
  <li>AR-DO (E3) is extended to include PERM-AR-DO (DB), which is an 8-byte bit
  mask representing 64 separate permissions.</li>
</ul>

<p>If PKG-REF-DO is not present, any app signed by the certificate is granted
access; otherwise both certificate and package name need to match.</p>

<h3 id=rule_example>Rule example</h3>
<p>The application name is <code>com.google.android.apps.myapp</code> and the
SHA-1 certificate in hex string is:</p>
<pre class="devsite-click-to-copy">
AB:CD:92:CB:B1:56:B2:80:FA:4E:14:29:A6:EC:EE:B6:E5:C1:BF:E4
</pre>

<p>The rule on UICC in hex string is:</p>
<pre class="devsite-click-to-copy">
E243 &lt;= 43 is value length in hex
  E135
    C114 ABCD92CBB156B280FA4E1429A6ECEEB6E5C1BFE4
    CA1D 636F6D2E676F6F676C652E616E64726F69642E617070732E6D79617070
  E30A
    DB08 0000000000000001
</pre>

<h2 id=arf>Access Rule File (ARF) support</h2>
<p>Android 7.0 adds support for reading carrier privilege rules from the Access
Rule File (ARF).</p>
<p>The Android platform first attempts to select the Access Rule Applet (ARA)
application identifier (AID) <code>A00000015141434C00</code>. If it doesn't find
the AID on the Universal Integrated Circuit Card (UICC), it falls back to ARF by
selecting PKCS15 AID <code>A000000063504B43532D3135</code>. Android then reads
Access Control Rules File (ACRF) at <code>0x4300</code> and looks for entries
with AID <code>FFFFFFFFFFFF</code>. Entries with different AIDs are ignored, so
rules for other use cases can co-exist.</p>
<p>Example ACRF content in hex string:</p>
<pre class="devsite-click-to-copy">
30 10 A0 08 04 06 FF FF FF FF FF FF 30 04 04 02 43 10
</pre>

<p>Example Access Control Conditions File (ACCF) content:</p>
<pre class="devsite-click-to-copy">
30 16 04 14 61 ED 37 7E 85 D3 86 A8 DF EE 6B 86 4B D8 5B 0B FA A5 AF 81
</pre>

<p>In above example, <code>0x4310</code> is the address for ACCF, which contains
the certificate hash
<code>61:ED:37:7E:85:D3:86:A8:DF:EE:6B:86:4B:D8:5B:0B:FA:A5:AF:81</code>. Apps
signed by this certificate are granted carrier privileges.</p>

<h2 id=enabled_apis>Enabled APIs</h2>

<p>Android supports the following APIs.</p>

<h3 id=telephonymanager>TelephonyManager</h3>

<ul>
<li>API to allow the carrier application to ask UICC for a challenge/response:
<a href="https://developer.android.com/reference/android/telephony/TelephonyManager.html#getIccAuthentication(int,%20int,%20java.lang.String)"><code>getIccAuthentication</code></a>.
</li>

<li>API to check whether calling application has been granted carrier
privileges:
<a href="http://developer.android.com/reference/android/telephony/TelephonyManager.html#hasCarrierPrivileges()"><code>hasCarrierPrivileges</code></a>.
</li>

<li>APIs to override brand and number:
<ul>
  <li><code>setOperatorBrandOverride</code></li>
  <li><code>setLine1NumberForDisplay</code></li>
  <li><code>setVoiceMailNumber</code></li>
</ul></li>

<li>APIs for direct UICC communication:
<ul>
  <li><code>iccOpenLogicalChannel</code></li>
  <li><code>iccCloseLogicalChannel</code></li>
  <li><code>iccExchangeSimIO</code></li>
  <li><code>iccTransmitApduLogicalChannel</code></li>
  <li><code>iccTransmitApduBasicChannel</code></li>
  <li><code>sendEnvelopeWithStatus</code></li>
</ul></li>

<li>API to set device mode to global:
<code>setPreferredNetworkTypeToGlobal</code>.</li>
</ul>

<h3 id=smsmanager>SmsManager</h3>

<p>API to allow caller to create new incoming SMS messages:
<code>injectSmsPdu</code>.</p>

<h3 id=carrierconfigmanager>CarrierConfigManager</h3>

<p>API to notify configuration changed:
<code>notifyConfigChangedForSubId</code>. For instructions, see
<a href="/devices/tech/config/carrier.html">Carrier Configuration</a>.
</p>

<h3 id=carriermessagingservice>CarrierMessagingService</h3>

<p>Service that receives calls from the system when new SMS and MMS are sent
or received. To extend this class, declare the service in your manifest file
with the <code>android.Manifest.permission#BIND_CARRIER_MESSAGING_SERVICE</code>
permission and include an intent filter with the <code>#SERVICE_INTERFACE</code>
action. APIs include:</p>
<ul>
  <li><code>onFilterSms</code></li>
  <li><code>onSendTextSms</code></li>
  <li><code>onSendDataSms</code></li>
  <li><code>onSendMultipartTextSms</code></li>
  <li><code>onSendMms</code></li>
  <li><code>onDownloadMms</code></li>
</ul>

<h3 id=telephonyprovider>TelephonyProvider</h3>

<p>Content provider APIs to allow modifications (insert, delete, update, query)
to the telephony database. Values fields are defined at
<a href="https://developer.android.com/reference/android/provider/Telephony.Carriers.html"><code>Telephony.Carriers</code></a>;
for more details, refer to
<a href="https://developer.android.com/reference/android/provider/Telephony.html">Telephony</a>
API reference on developer.android.com.</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"><code>UiccCarrierPrivilegeRules.java</code></a>
loads rules, parses them from the UICC card, and caches them in memory. When
a privilege check is needed, <code>UiccCarrierPrivilegeRules</code> compares the
caller certificate with its own rules one by one. If the UICC is removed, rules
are destroyed along with the UICC object.</p>

<h2 id=validation>Validation</h2>
<p>The Android 7.0 CTS includes tests for carrier APIs in
<code>CtsCarrierApiTestCases.apk</code>. Because this feature depends on
certificates on the UICC, you must prepare the UICC to pass these tests.</p>

<h3 id=prepare_uicc>Preparing the UICC</h3>
<p>By default, <code>CtsCarrierApiTestCases.apk</code> is signed by Android
developer key, with hash value
<code>61:ED:37:7E:85:D3:86:A8:DF:EE:6B:86:4B:D8:5B:0B:FA:A5:AF:81</code>. The
tests also print out the expected certificate hash if certificates on UICC
mismatch.</p>
<p>Example output:</p>
<pre class="devsite-click-to-copy">
junit.framework.AssertionFailedError: This test requires a SIM card with carrier privilege rule on it.
Cert hash: 61ed377e85d386a8dfee6b864bd85b0bfaa5af81
</pre>

<p>In order to validate the implementation via CTS using
<code>CtsCarrierApiTestCases.apk</code>, you must have a developer UICC with
the correct UICC rules or ARF support. You may ask the SIM card vendor
of your choice to prepare a developer UICC with the right ARF as described in
this section and use that UICC to run the tests. The UICC does not require
active cellular service to pass CTS tests.</p>

<h3 id=run_tests>Running tests</h3>
<p>For convenience, the Android 7.0 CTS supports a device token that restricts
tests to run only on devices configured with same token. Carrier API CTS tests
support the device token <code>sim-card-with-certs</code>. For example, the
following device token restricts carrier API tests to run only on device
<code>abcd1234</code>:</p>
<pre class="devsite-terminal devsite-click-to-copy">
cts-tradefed run cts  --device-token abcd1234:sim-card-with-certs
</pre>

<p>When running a test without using a device token, the test runs on all
devices.</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: Its 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 doesnt 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? (i.e. Will you have tests to validate which APIs are supported
via this method?)</strong></p>

<p><em>A: See the "API Behavioral Compatibility" section of the
<a href="/compatibility/cdd.html">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?</strong></p>
<p><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></p>

<p><strong>When is it a good time to check carrier privileges?</strong></p>
<p><em>A: After the SIM state loaded broadcast.</em></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: Refer to the SPN entry in
<a href="http://developer.android.com/reference/android/telephony/TelephonyManager.html">TelephonyManager</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: The deviceAppID storing certificates is already supported by the
existing spec. We tried to minimize spec changes to lower barrier for adoption.
For details, see <a href="#rules_on_uicc">Rules on UICC</a>.</em></p>

  </body>
</html>