1<!-- 2 Copyright (C) 2021 The Android Open Source Project 3 4 Licensed under the Apache License, Version 2.0 (the "License"); 5 you may not use this file except in compliance with the License. 6 You may obtain a copy of the License at 7 8 http://www.apache.org/licenses/LICENSE-2.0 9 10 Unless required by applicable law or agreed to in writing, software 11 distributed under the License is distributed on an "AS IS" BASIS, 12 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 See the License for the specific language governing permissions and 14 limitations under the License 15 --> 16 17# Using role for permission protection 18 19Since Android S, it is possible to use `role` as a protection flag for permission definitions. This 20allows more fine-grained control over which apps may get certain permissions, instead of the 21`signature` or `privileged` protection that allows any platform-signed or privileged app to obtain 22the permission. This was previously achieved via role-like protection flags, e.g. `installer` and 23`verifier`, but they are essentially roles with a poorer implementation, and each of them takes one 24bit from the protection flags so that we will be running out of bits soon. 25 26The following outlines how to add a new permission with the role protection flag. 27 28## Add (or modify) the permission definition 29 30Edit `frameworks/base/core/res/AndroidManifest.xml` to add your new permission: 31 32```xml 33<!-- The javadoc for your new permission. --> 34<permission 35 android:name="android.permission.YOUR_NEW_PERMISSION" 36 android:protectionLevel="internal|role" /> 37``` 38 39The choice of `android:protectionLevel` depends on your actual situation/requirements. More 40specifically: 41 42- `internal|role`: This enforces that only role may grant this permission to apps, which is the 43preferred protection if possible. 44- `signature|role`: This allows platform-signed apps to get this permission in addition to role 45grants. 46- `<previous-protection-level>|role`: Adding the `role` protection flag while keeping the original 47protection level of an existing permission may allow a smoother transition to role permission 48protection. 49 50## Add the role 51 52Edit [roles.xml](../../../../../res/xml/roles.xml) to add your new role: 53 54```xml 55<role 56 name="android.app.role.SYSTEM_YOUR_ROLE_NAME" 57 defaultHolders="config_systemYourRoleName" 58 exclusive="true" 59 minSdkVersion="31" 60 static="true" 61 systemOnly="true" 62 visible="false"> 63 <permissions> 64 <permission name="android.permission.YOUR_NEW_PERMISSION" /> 65 </permissions> 66</role> 67``` 68 69The role is named with the `SYSTEM_` prefix to indicate that it is an invisible and system app only 70role. The config resource `config_systemYourRoleName` will be added in the next step, and more 71details about role are available in [Android Role for system developers](Role.md). The 72`minSdkVersion` attribute should normally be set to the current SDK version, to avoid making the 73role available on older platforms. 74 75If you are writing a CTS test for an API protected by an `internal|role` permission, you probably 76want to grant the permission to Shell as well. This can be achieved by adding the permission to the 77`SYSTEM_SHELL` role in `roles.xml`. 78 79## Add the default role holder config 80 81Now that we have a role, we need to define a platform config resource to initialize it with your 82desired package name so that it may obtain the permission. 83 84Edit `frameworks/base/core/res/res/values/config.xml` to add your new config resource: 85 86```xml 87<string name="config_systemYourRoleName" translatable="false">your.package.name</string> 88``` 89 90You may also leave the package name empty in platform and override in a device/vendor-specific 91overlay. 92 93Since role is modularized, we also need to make this config resource a system API for access by 94role. 95 96Edit `frameworks/base/core/res/res/values/public.xml` to expose the new config resource as a system 97API: 98 99```xml 100<public-group type="string" first-id="0xXXXXXXXX"> 101 <!-- @hide @SystemApi --> 102 <public name="config_systemYourRoleName" /> 103</public-group> 104``` 105 106Then run `m update-api` to update the API text files. 107 108## Upload the changes for review 109 110Finally, upload the changes to Gerrit in one topic, then add the appropriate owners for review. Once 111the changes are submitted, you will have a working role protected permission. 112