Docs: Add UICC Carrier Privileges to Config section
Bug: 23208301
Change-Id: I350cc24d1452296efbf5d988b479df02c795be7b
diff --git a/src/devices/devices_toc.cs b/src/devices/devices_toc.cs
index 1d8069b..a7a1b18 100644
--- a/src/devices/devices_toc.cs
+++ b/src/devices/devices_toc.cs
@@ -197,6 +197,7 @@
<li><a href="<?cs var:toroot ?>devices/tech/config/low-ram.html">Low RAM</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/renderer.html">OpenGLRenderer</a></li>
<li><a href="<?cs var:toroot ?>devices/tech/config/runtime_perms.html">Runtime Permissions</a></li>
+ <li><a href="<?cs var:toroot ?>devices/tech/config/uicc.html">UICC</a></li>
</ul>
</li>
diff --git a/src/devices/tech/config/uicc.jd b/src/devices/tech/config/uicc.jd
new file mode 100644
index 0000000..762e25d
--- /dev/null
+++ b/src/devices/tech/config/uicc.jd
@@ -0,0 +1,310 @@
+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>
