354 lines
15 KiB
HTML
354 lines
15 KiB
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) owner’s 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 <= 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: 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? (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>
|