diff options
author | Heidi von Markham <hvm@google.com> | 2016-07-22 10:19:10 -0700 |
---|---|---|
committer | Heidi von Markham <hvm@google.com> | 2016-07-22 10:19:10 -0700 |
commit | 6b6eeb7f6b219fc2fdc55cbff2f7a7c8219ee895 (patch) | |
tree | 7e7e722468b76a3633c3de2880ac43dab288ef5a | |
parent | 27cc4e44105864624194550430798f4f178da516 (diff) | |
download | source.android.com-6b6eeb7f6b219fc2fdc55cbff2f7a7c8219ee895.tar.gz |
Docs: New CL for carrier arf changes
Bug: 27207118
Change-Id: I031b7b25cb6f42bddbfa91c2f06a69b23e2ecb7f
-rw-r--r-- | src/devices/tech/config/uicc.jd | 402 |
1 files changed, 217 insertions, 185 deletions
diff --git a/src/devices/tech/config/uicc.jd b/src/devices/tech/config/uicc.jd index 762e25d6..c93b91c3 100644 --- a/src/devices/tech/config/uicc.jd +++ b/src/devices/tech/config/uicc.jd @@ -24,55 +24,60 @@ page.title=UICC Carrier Privileges </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> +<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="{@docRoot}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 +<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> +(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> -<p>Each rule is a REF-AR-DO (E2) and consists of a concatenation of a REF-DO and -an AR-DO:</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. + 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. + <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 will be granted +<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=example>Example</h3> +<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>AB:CD:92:CB:B1:56:B2:80:FA:4E:14:29:A6:EC:EE:B6:E5:C1:BF:E4</pre> -<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> +<p>The rule on UICC in hex string is:</p> <pre> E243 <= 43 is value length in hex E135 @@ -82,229 +87,256 @@ E243 <= 43 is value length in hex DB08 0000000000000001 </pre> -<h2 id=enabled_apis>Enabled APIs</h2> +<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>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>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>Currently we support the following APIs, listed below (refer to -developer.android.com for more details).</p> +<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> -<h3 id=telephonymanager>TelephonyManager</h3> +<h2 id=enabled_apis>Enabled APIs</h2> -<p>API to check whether calling application has been granted carrier privileges:</p> +<p>Android supports the following APIs.</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> +<h3 id=telephonymanager>TelephonyManager</h3> -<pre> -setOperatorBrandOverride -setLine1NumberForDisplay -setVoiceMailNumber -</pre> +<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> -<p>APIs for direct UICC communication:</p> +<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> -<pre> -iccOpenLogicalChannel -iccCloseLogicalChannel -iccExchangeSimIO -iccTransmitApduLogicalChannel -iccTransmitApduBasicChannel -sendEnvelopeWithStatus -</pre> - -<p>API to set device mode to global:</p> +<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> -<pre> -setPreferredNetworkTypeToGlobal -</pre> +<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 allows caller to create new incoming SMS messages:</p> +<p>API to allow caller to create new incoming SMS messages: +<code>injectSmsPdu</code>.</p> -<pre> -injectSmsPdu -</pre> +<h3 id=carrierconfigmanager>CarrierConfigManager</h3> -<h4 id=carriermessagingservice>CarrierMessagingService</h4> +<p>API to notify configuration changed: +<code>notifyConfigChangedForSubId</code>. For instructions, see +<a href="{@docRoot}devices/tech/config/carrier.html">Carrier Configuration</a>. +</p> -<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> +<h3 id=carriermessagingservice>CarrierMessagingService</h3> -<pre> -onFilterSms -onSendTextSms -onSendDataSms -onSendMultipartTextSms -onSendMms -onDownloadMms -</pre> +<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> -<h4 id=telephonyprovider>TelephonyProvider</h4> +<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> -<p>Content provider APIs that allow modification to the telephony database, value -fields are defined at Telephony.Carriers:</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> -insert, delete, update, query +junit.framework.AssertionFailedError: This test requires a SIM card with carrier privilege rule on it. +Cert hash: 61ed377e85d386a8dfee6b864bd85b0bfaa5af81 </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> +<p>You may need a developer UICC to update it with the correct applet and +certificate rules. However, the UICC does not require active cellular service to +pass CTS tests.</p> -<h2 id=android_platform>Android platform</h2> +<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>cts-tradefed run cts --device-token abcd1234:sim-card-with-certs</pre> -<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> +<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><strong>How can certificates be updated on the UICC?</strong></p> -<p><em>A: Use existing card OTA update mechanism. -</em></p> +<p><em>A: Use existing card OTA update mechanism.</em></p> -<p><strong>Can it co-exist with other rules? -</strong></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> +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> +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><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><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><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><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><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: 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><em>A: See the "API Behavioral Compatibility" section of the +<a href="{@docRoot}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><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>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? -<em>A: After the SIM state loaded broadcast.</em> -</strong></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><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><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><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> +<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><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><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><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> +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><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><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> +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> +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><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 +<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><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> +<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> |