android_manifest/permission.rs
1use super::resources::{
2 MipmapOrDrawableResource, Resource, StringResource, StringResourceOrString,
3};
4use serde::{Deserialize, Serialize};
5
6/// Declares a security permission.
7///
8/// That can be used to limit access to specific components or features of this
9/// or other applications. See the [`Permissions`] section in the introduction, and the
10/// [`Security and Permissions`] document for more information on how permissions work.
11///
12/// ## XML Syntax
13/// ```xml
14/// <permission android:description="string resource"
15/// android:icon="drawable resource"
16/// android:label="string resource"
17/// android:name="string"
18/// android:permissionGroup="string"
19/// android:protectionLevel=["normal" | "dangerous" |
20/// "signature" | ...] />
21/// ```
22///
23/// ## Contained in
24/// * [`<manifest>`]
25///
26/// ## Introduced in
27/// API Level 1
28///
29/// [`<manifest>`]: crate::AndroidManifest
30/// [`Permissions`]: https://developer.android.com/guide/topics/manifest/manifest-intro#perms
31/// [`Security and Permissions`]: https://developer.android.com/training/articles/security-tips
32#[derive(
33 Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Default, Clone,
34)]
35pub struct Permission {
36 /// A user-readable description of the permission, longer and more informative than
37 /// the label. It may be displayed to explain the permission to the user — for
38 /// example, when the user is asked whether to grant the permission to another
39 /// application.
40 ///
41 /// This attribute must be set as a reference to a string resource; unlike the `label`
42 /// unlike the `label` attribute, it cannot be a raw string.
43 #[yaserde(attribute, prefix = "android")]
44 pub description: Option<Resource<StringResource>>,
45 /// A reference to a drawable resource for an icon that represents the permission.
46 #[yaserde(attribute, prefix = "android")]
47 pub icon: Option<MipmapOrDrawableResource>,
48 /// A name for the permission, one that can be displayed to users. As a convenience,
49 /// the label can be directly set as a raw string while you're developing the
50 /// application. However, when the application is ready to be published, it should
51 /// be set as a reference to a string resource, so that it can be localized like
52 /// other strings in the user interface.
53 #[yaserde(attribute, prefix = "android")]
54 pub label: Option<StringResourceOrString>,
55 /// The name of the permission. This is the name that will be used in code to refer to
56 /// the permission — for example, in a [`<uses-permission>`] element and the
57 /// permission attributes of application components.
58 ///
59 /// ## Note
60 /// The system does not allow multiple packages to declare a permission with
61 /// the same name, unless all the packages are signed with the same
62 /// certificate. If a package declares a permission, the system does not
63 /// permit the user to install other packages with the same permission
64 /// name, unless those packages are signed with the same certificate as
65 /// the first package. To avoid naming collisions, we recommend using
66 /// reverse-domain-style naming for custom permissions, for example
67 /// `com.example.myapp.ENGAGE_HYPERSPACE`.
68 ///
69 /// [`<uses-permission>`]: crate::UsesPermission
70 #[yaserde(attribute, prefix = "android")]
71 pub name: Option<String>,
72 /// Assigns this permission to a group. The value of this attribute is the name of the
73 /// group, which must be declared with the [`<permission-group>`] element in this
74 /// or another application. If this attribute is not set, the permission does not
75 /// belong to a group.
76 ///
77 /// [`<permission-group>`]: crate::PermissionGroup
78 #[yaserde(attribute, prefix = "android", rename = "permissionGroup")]
79 pub permission_group: Option<String>,
80 /// Characterizes the potential risk implied in the permission and indicates the
81 /// procedure the system should follow when determining whether or not to grant
82 /// the permission to an application requesting it.
83 ///
84 /// Each protection level consists of a base permission type and zero or more flags.
85 /// For example, the `"dangerous"` protection level has no flags. In contrast,
86 /// the protection level `"signature|privileged"` is a combination of the
87 /// `"signature"` base permission type and the `"privileged"` flag.
88 #[yaserde(attribute, prefix = "android", rename = "protectionLevel")]
89 pub protection_level: Option<ProtectionLevel>,
90}
91
92/// The following table shows all base permission types. For a list of flags,
93/// see [`protectionLevel`].
94///
95/// [`protectionLevel`]: https://developer.android.com/reference/android/R.attr#protectionLevel
96#[derive(Debug, Deserialize, Serialize, YaSerialize, YaDeserialize, PartialEq, Eq, Clone)]
97#[serde(rename_all = "camelCase")]
98#[derive(Default)]
99pub enum ProtectionLevel {
100 /// The default value. A lower-risk permission that gives requesting applications
101 /// access to isolated application-level features, with minimal risk to other
102 /// applications, the system, or the user. The system automatically grants this
103 /// type of permission to a requesting application at installation, without asking
104 /// for the user's explicit approval (though the user always has the option to
105 /// review these permissions before installing).
106 #[yaserde(rename = "normal")]
107 #[default]
108 Normal,
109 /// A higher-risk permission that would give a requesting application access to
110 /// private user data or control over the device that can negatively impact the
111 /// user. Because this type of permission introduces potential risk, the system
112 /// may not automatically grant it to the requesting application. For example, any
113 /// dangerous permissions requested by an application may be displayed to the user
114 /// and require confirmation before proceeding, or some other approach may
115 /// be taken to avoid the user automatically allowing the use of such
116 /// facilities.
117 #[yaserde(rename = "dangerous")]
118 Dangerous,
119 /// A permission that the system grants only if the requesting application is signed
120 /// with the same certificate as the application that declared the permission. If
121 /// the certificates match, the system automatically grants the permission without
122 /// notifying the user or asking for the user's explicit approval.
123 #[yaserde(rename = "signature")]
124 Signature,
125 /// Old synonym for `"signature|privileged"`. Deprecated in API level 23. A permission
126 /// that the system grants only to applications that are in a dedicated folder on
127 /// the Android system image or that are signed with the same certificate as the
128 /// application that declared the permission. Avoid using this option, as the
129 /// signature protection level should be sufficient for most needs and works
130 /// regardless of exactly where apps are installed.
131 /// The "signatureOrSystem" permission is used for certain special
132 /// situations where multiple vendors have applications
133 /// built into a system image and need to share specific features
134 /// explicitly because they are being built together.
135 #[yaserde(rename = "signatureOrSystem")]
136 SignatureOrSystem,
137}