Merge "docs: Noted that custom permissions must be unique per-device" into mnc-mr-docs am: 9be023f077 am: 76f95f5571 am: dc4cd59183

am: 8363a70024

* commit '8363a70024a53f4934639a1e6c13aae17f4d6d0c':
  docs: Noted that custom permissions must be unique per-device

Change-Id: Ida453b78baa5e40a9d2f9241d34ac5ad172efbcd

docs/html/guide/topics/manifest/permission-element.jd

@@ -10,70 +10,80 @@ parent.link=manifest-intro.html
             android:<a href="#label">label</a>="<i>string resource</i>"
             android:<a href="#nm">name</a>="<i>string</i>"
             android:<a href="#pgroup">permissionGroup</a>="<i>string</i>"
-            android:<a href="#plevel">protectionLevel</a>=["normal" | "dangerous" | 
+            android:<a href="#plevel">protectionLevel</a>=["normal" | "dangerous" |
                                      "signature" | "signatureOrSystem"] /&gt;</pre></dd>
 
 <dt>contained in:</dt>
-<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html">&lt;manifest&gt;</a></code></dd>
+<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"
+  >&lt;manifest&gt;</a></code></dd>
 
 <dt>description:</dt>
-<dd itemprop="description">Declares a security permission that can be used to limit access
+<dd itemprop="description">Declares a security permission that can be used to
-to specific components or features of this or other applications.  
+limit access to specific components or features of this or other applications.
-See the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a>
+See the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms"
-section in the introduction,
+>Permissions</a> section in the introduction, and the <a
-and the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> 
+href="{@docRoot}guide/topics/security/security.html">Security and
-document for more information on how permissions work.</dd>
+Permissions</a> document for more information on how permissions work.</dd>
 
 <dt>attributes:</dt>
 <dd><dl class="attr">
 <dt><a name="desc"></a>{@code android:description}</dt>
-<dd>A user-readable description of the permission, longer and more 
+<dd>A user-readable description of the permission, longer and more
-informative than the label.  It may be displayed to explain the 
+informative than the label.  It may be displayed to explain the
-permission to the user &mdash; for example, when the user is asked 
+permission to the user &mdash; for example, when the user is asked
 whether to grant the permission to another application.
 
 <p>
-This attribute must be set as a reference to a string resource; 
+This attribute must be set as a reference to a string resource;
 unlike the {@code label} attribute, it cannot be a raw string.
 </p></dd>
 
 <dt><a name="icon"></a>{@code android:icon}</dt>
-<dd>A reference to a drawable resource for an icon that represents the 
+<dd>A reference to a drawable resource for an icon that represents the
 permission.</dd>
 
 <dt><a name="label"></a>{@code android:label}</dt>
-<dd>A name for the permission, one that can be displayed to users. 
+<dd>A name for the permission, one that can be displayed to users.
 
 <p>
-As a convenience, the label can be directly set 
+As a convenience, the label can be directly set
-as a raw string while you're developing the application.  However, 
+as a raw string while you're developing the application.  However,
-when the application is ready to be published, it should be set as a 
+when the application is ready to be published, it should be set as a
-reference to a string resource, so that it can be localized like other 
+reference to a string resource, so that it can be localized like other
 strings in the user interface.
 </p></dd>
 
 <dt><a name="nm"></a>{@code android:name}</dt>
-<dd>The name of the permission.  This is the name that will be used in 
+<dd>The name of the permission.  This is the name that will be used in
-code to refer to the permission &mdash; for example, in a 
+code to refer to the permission &mdash; for example, in a
-<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html">&lt;uses-permission&gt;</a></code> element and the
+<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"
+  >&lt;uses-permission&gt;</a></code> element and the
 {@code permission} attributes of application components.
 
-<p>
+
-The name must be unique, so it should use Java-style scoping &mdash; 
+<p class="note">
-for example, "{@code com.example.project.PERMITTED_ACTION}".
+  <strong>Note:</strong> The system does not allow multiple packages to declare
-</p></dd>
+  a permission with the same name, unless all the packages are signed with the
+  same certificate. If a package declares a permission, the system does not permit
+  the user to install other packages with the same permission name, unless
+  those packages are signed with the same certificate as the first package. To
+  avoid naming collisions, we recommend using reverse-domain-style naming for custom
+  permissions, for example <code>com.example.myapp.ENGAGE_HYPERSPACE</code>.
+</p>
+</dd>
 
 <dt><a name="pgroup"></a>{@code android:permissionGroup}</dt>
-<dd>Assigns this permission to a group.  The value of this attribute is 
+<dd>Assigns this permission to a group.  The value of this attribute is
-the name of the group, which must be declared with the 
+the name of the group, which must be declared with the
-<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html">&lt;permission-group&gt;</a></code> element in this 
+<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"
+  >&lt;permission-group&gt;</a></code> element in this
 or another application.  If this attribute is not set, the permission
 does not belong to a group.</dd>
 
 <dt><a name="plevel"></a>{@code android:protectionLevel}</dt>
 <dd>Characterizes the potential risk implied in the permission and
 indicates the procedure the system should follow when determining
-whether or not to grant the permission to an application requesting it. 
+whether or not to grant the permission to an application requesting it.
 The value can be set to one of the following strings:
 
 <table>
@@ -82,9 +92,9 @@ The value can be set to one of the following strings:
    <th>Meaning</th>
 </tr><tr>
    <td>"{@code normal}"</td>
-   <td>The default value.  A lower-risk permission that gives requesting 
+   <td>The default value.  A lower-risk permission that gives requesting
-       applications access to isolated application-level features, with 
+       applications access to isolated application-level features, with
-       minimal risk to other applications, the system, or the user.  
+       minimal risk to other applications, the system, or the user.
        The system automatically grants this type
        of permission to a requesting application at installation, without
        asking for the user's explicit approval (though the user always
@@ -109,11 +119,11 @@ The value can be set to one of the following strings:
        asking for the user's explicit approval.
 </tr><tr>
    <td>"{@code signatureOrSystem}"</td>
-   <td>A permission that the system grants only to applications that are 
+   <td>A permission that the system grants only to applications that are
        in the Android system image <em>or</em> that are signed with the same
-       certificate as the application that declared the permission. Please avoid using this 
+       certificate as the application that declared the permission. Please avoid using this
-       option, as the {@code signature} protection level should be sufficient 
+       option, as the {@code signature} protection level should be sufficient
-       for most needs and works regardless of exactly where applications are 
+       for most needs and works regardless of exactly where applications are
        installed.  The "{@code signatureOrSystem}"
        permission is used for certain special situations where multiple
        vendors have applications built into a system image and need

docs/html/guide/topics/security/permissions.jd

@@ -18,6 +18,7 @@ page.tags=permissions
 </li>
 <li><a href="#defining">Defining and Enforcing Permissions</a>
 	<ol>
+  <li><a href="#custom-recommendations">Custom permission recommendations</a></li>
 	<li><a href="#manifest">...in AndroidManifest.xml</a></li>
 	<li><a href="#broadcasts">...when Sending Broadcasts</a></li>
 	<li><a href="#enforcement">Other Permission Enforcement</a></li>
@@ -540,17 +541,19 @@ to be as high as possible. You can see which permissions were added with each re
 <a name="declaring"></a>
 <h2 id="defining">Defining and Enforcing Permissions</h2>
 
-<p>To enforce your own permissions, you must first declare them in your
+<p>
-<code>AndroidManifest.xml</code> using one or more
+  To enforce your own permissions, you must first declare them in your
-<code>{@link android.R.styleable#AndroidManifestPermission &lt;permission&gt;}</code>
+  <code>AndroidManifest.xml</code> using one or more <a href=
-tags.</p>
+  "{@docRoot}guide/topics/manifest/permission-element.html"><code>&lt;permission&gt;</code></a>
+  elements.
+</p>
 
 <p>For example, an application that wants to control who can start one
 of its activities could declare a permission for this operation as follows:</p>
 
 <pre>&lt;manifest xmlns:android=&quot;http://schemas.android.com/apk/res/android&quot;
-    package=&quot;com.me.app.myapp&quot; &gt;
+    package=&quot;com.example.myapp&quot; &gt;
-    &lt;permission android:name=&quot;com.me.app.myapp.permission.DEADLY_ACTIVITY&quot;
+    &lt;permission android:name=&quot;com.example.myapp.permission.DEADLY_ACTIVITY&quot;
         android:label=&quot;&#64;string/permlab_deadlyActivity&quot;
         android:description=&quot;&#64;string/permdesc_deadlyActivity&quot;
         android:permissionGroup=&quot;android.permission-group.COST_MONEY&quot;
@@ -558,50 +561,65 @@ of its activities could declare a permission for this operation as follows:</p>
     ...
 &lt;/manifest&gt;</pre>
 
+<p class="note">
+  <strong>Note:</strong> The system does not allow multiple packages to declare
+  a permission with the same name, unless all the packages are signed with the
+  same certificate. If a package declares a permission, the system does not permit
+  the user to install other packages with the same permission name, unless
+  those packages are signed with the same certificate as the first package. To
+  avoid naming collisions, we recommend using reverse-domain-style naming for custom
+  permissions, for example <code>com.example.myapp.ENGAGE_HYPERSPACE</code>.
+</p>
+
 <p>The {@link android.R.styleable#AndroidManifestPermission_protectionLevel
-&lt;protectionLevel&gt;} attribute is required, telling the system how the
+protectionLevel} attribute is required, telling the system how the
 user is to be informed of applications requiring the permission, or who is
 allowed to hold that permission, as described in the linked documentation.</p>
 
-<p>The {@link android.R.styleable#AndroidManifestPermission_permissionGroup
+<p>
-&lt;permissionGroup&gt;} attribute is optional, and only used to help the system display
+  The <a href=
-permissions to the user.  You will usually want to set this to either a standard
+  "{@docRoot}guide/topics/manifest/permission-group-element.html"
-system group (listed in {@link android.Manifest.permission_group
+  ><code>android:permissionGroup</code></a>
-android.Manifest.permission_group}) or in more rare cases to one defined by
+  attribute is optional, and only used to help the system display permissions
-yourself.  It is preferred to use an existing group, as this simplifies the
+  to the user. In most cases you will want to set this to a standard system
-permission UI shown to the user.</p>
+  group (listed in {@link android.Manifest.permission_group
+  android.Manifest.permission_group}), although you can define a group yourself.
+  It is preferable to use an existing group, as this simplifies the
+  permission UI shown to the user.
+</p>
 
-<p>Note that both a label and description should be supplied for the
+<p>You need to supply both a label and description for the
-permission. These are string resources that can be displayed to the user when
+permission. These are string resources that the user can see when
 they are viewing a list of permissions
 (<code>{@link android.R.styleable#AndroidManifestPermission_label android:label}</code>)
 or details on a single permission (
 <code>{@link android.R.styleable#AndroidManifestPermission_description android:description}</code>).
-The label should be short, a few words
+The label should be short; a few words
 describing the key piece of functionality the permission is protecting. The
-description should be a couple sentences describing what the permission allows
+description should be a couple of sentences describing what the permission allows
-a holder to do. Our convention for the description is two sentences, the first
+a holder to do. Our convention is a two-sentence description:
-describing the permission, the second warning the user of what bad things
+the first sentence describes the permission, and the second sentence warns the
-can happen if an application is granted the permission.</p>
+user of the type of things that can go wrong if an application is granted the
+permission.</p>
 
 <p>Here is an example of a label and description for the CALL_PHONE
 permission:</p>
 
 <pre>
-    &lt;string name=&quot;permlab_callPhone&quot;&gt;directly call phone numbers&lt;/string&gt;
+&lt;string name=&quot;permlab_callPhone&quot;&gt;directly call phone numbers&lt;/string&gt;
-    &lt;string name=&quot;permdesc_callPhone&quot;&gt;Allows the application to call
+&lt;string name=&quot;permdesc_callPhone&quot;&gt;Allows the application to call
-        phone numbers without your intervention. Malicious applications may
+    phone numbers without your intervention. Malicious applications may
-        cause unexpected calls on your phone bill. Note that this does not
+    cause unexpected calls on your phone bill. Note that this does not
-        allow the application to call emergency numbers.&lt;/string&gt;
+    allow the application to call emergency numbers.&lt;/string&gt;
 </pre>
 
-<p>You can look at the permissions currently defined in the system with the
+<p>You can view at the permissions currently defined in the system using the
 Settings app and the shell command <code>adb shell pm list permissions</code>.
-To use the Settings app, go to Settings &gt; Applications.  Pick an app and
+To use the Settings app, go to <b>Settings</b> &gt; <b>Applications</b>.  Pick an app and
 scroll down to see the permissions that the app uses. For developers, the adb '-s'
 option displays the permissions in a form similar to how the user will see them:</p>
 
-<pre>
+<pre class="no-pretty-print">
 $ adb shell pm list permissions -s
 All Permissions:
 
@@ -615,14 +633,53 @@ Services that cost you money: send SMS messages, directly call phone numbers
 
 ...</pre>
 
+<h3 id="custom-recommendations">
+  Custom permission recommendations
+</h3>
+
+<p>
+  Apps can define their own custom permissions and request custom permissions
+  from other apps by defining <a href=
+  "{@docRoot}guide/topics/manifest/uses-permission-element.html"><code
+  >&lt;uses-permission&gt;</code></a> elements.
+  However, you should carefully assess whether it is necessary for your app to
+  do so.
+</p>
+
+<ul>
+  <li>If you are designing a suite of apps that expose functionality to one
+  another, try to design the apps so that each permission is defined only once.
+  You must do this if the apps are not all signed with the same certificate.
+  Even if the apps are all signed with the same certificate, it's a
+  best practice to define each permission once only.
+  </li>
+
+  <li>If the functionality is only available to apps signed with the same
+  signature as the providing app, you may be able to avoid defining custom
+  permissions by using signature checks. When one of your apps makes a request
+  of another of your apps, the second app can verify that both apps are signed
+  with the same certificate before complying with the request.
+  </li>
+
+  <li>If you are developing a suite of apps runs only on your own
+  devices, you should develop and install a package that
+  manages permissions for all the apps in the suite. This package does not need
+  to provide any services itself. It just declares all the permissions, and the
+  other apps in the suite request those permissions with the <a href=
+  "{@docRoot}guide/topics/manifest/uses-permission-element.html"><code
+  >&lt;uses-permission&gt;</code></a>
+  element.
+  </li>
+</ul>
+
 <a name="manifest"></a>
 <h3>Enforcing Permissions in AndroidManifest.xml</h3>
 
-<p>High-level permissions restricting access to entire components of the
+<p>TYou can apply high-level permissions restricting access to entire components
-system or application can be applied through your
+of the system or application through your
-<code>AndroidManifest.xml</code>. All that this requires is including an {@link
+<code>AndroidManifest.xml</code>. To do this, include an {@link
 android.R.attr#permission android:permission} attribute on the desired
-component, naming the permission that will be used to control access to
+component, naming the permission that controls access to
 it.</p>
 
 <p><strong>{@link android.app.Activity}</strong> permissions