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 package android.content.pm.verify.domain;
18 
19 import android.annotation.IntDef;
20 import android.annotation.NonNull;
21 
22 /**
23  * @hide
24  */
25 public interface DomainVerificationState {
26 
27     @IntDef({
28             STATE_NO_RESPONSE,
29             STATE_SUCCESS,
30             STATE_MIGRATED,
31             STATE_RESTORED,
32             STATE_APPROVED,
33             STATE_DENIED,
34             STATE_LEGACY_FAILURE,
35             STATE_SYS_CONFIG,
36             STATE_PRE_VERIFIED,
37             STATE_FIRST_VERIFIER_DEFINED,
38     })
39     @interface State {
40     }
41 
42     // TODO(b/159952358): Document all the places that states need to be updated when one is added
43     /**
44      * @see DomainVerificationInfo#STATE_NO_RESPONSE
45      */
46     int STATE_NO_RESPONSE = 0;
47 
48     /**
49      * @see DomainVerificationInfo#STATE_SUCCESS
50      */
51     int STATE_SUCCESS = 1;
52 
53     /**
54      * The system has chosen to ignore the verification agent's opinion on whether the domain should
55      * be verified. This will treat the domain as verified.
56      */
57     int STATE_APPROVED = 2;
58 
59     /**
60      * The system has chosen to ignore the verification agent's opinion on whether the domain should
61      * be verified. This will treat the domain as unverified.
62      */
63     int STATE_DENIED = 3;
64 
65     /**
66      * The state was migrated from the previous intent filter verification API. This will treat the
67      * domain as verified, but it should be updated by the verification agent. The older API's
68      * collection and handling of verifying domains may lead to improperly migrated state.
69      */
70     int STATE_MIGRATED = 4;
71 
72     /**
73      * The state was restored from a user backup or by the system. This is treated as if the domain
74      * was verified, but the verification agent may choose to re-verify this domain to be certain
75      * nothing has changed since the snapshot.
76      */
77     int STATE_RESTORED = 5;
78 
79     /**
80      * The domain was failed by a legacy intent filter verification agent from v1 of the API. This
81      * is made distinct from {@link #STATE_FIRST_VERIFIER_DEFINED} to prevent any v2 verification
82      * agent from misinterpreting the result, since {@link #STATE_FIRST_VERIFIER_DEFINED} is agent
83      * specific and can be defined as a special error code.
84      */
85     int STATE_LEGACY_FAILURE = 6;
86 
87     /**
88      * The application has been granted auto verification for all domains by configuration on the
89      * system image.
90      *
91      * TODO: Can be stored per-package rather than for all domains for a package to save memory.
92      */
93     int STATE_SYS_CONFIG = 7;
94 
95     /**
96      * The application has temporarily been granted auto verification for a set of domains as
97      * specified by a trusted installer during the installation. This will treat the domain as
98      * verified, but it should be updated by the verification agent.
99      */
100     int STATE_PRE_VERIFIED = 8;
101 
102     /**
103      * @see DomainVerificationInfo#STATE_FIRST_VERIFIER_DEFINED
104      */
105     int STATE_FIRST_VERIFIER_DEFINED = 0b10000000000;
106 
107     @NonNull
stateToDebugString(@omainVerificationState.State int state)108     static String stateToDebugString(@DomainVerificationState.State int state) {
109         switch (state) {
110             case DomainVerificationState.STATE_NO_RESPONSE:
111                 return "none";
112             case DomainVerificationState.STATE_SUCCESS:
113                 return "verified";
114             case DomainVerificationState.STATE_APPROVED:
115                 return "approved";
116             case DomainVerificationState.STATE_DENIED:
117                 return "denied";
118             case DomainVerificationState.STATE_MIGRATED:
119                 return "migrated";
120             case DomainVerificationState.STATE_RESTORED:
121                 return "restored";
122             case DomainVerificationState.STATE_LEGACY_FAILURE:
123                 return "legacy_failure";
124             case DomainVerificationState.STATE_SYS_CONFIG:
125                 return "system_configured";
126             case DomainVerificationState.STATE_PRE_VERIFIED:
127                 return "pre_verified";
128             default:
129                 return String.valueOf(state);
130         }
131     }
132 
133     /**
134      * For determining re-verify policy. This is hidden from the domain verification agent so that
135      * no behavior is made based on the result.
136      */
isDefault(@tate int state)137     static boolean isDefault(@State int state) {
138         switch (state) {
139             case STATE_NO_RESPONSE:
140             case STATE_MIGRATED:
141             case STATE_RESTORED:
142                 return true;
143             case STATE_SUCCESS:
144             case STATE_APPROVED:
145             case STATE_DENIED:
146             case STATE_LEGACY_FAILURE:
147             case STATE_SYS_CONFIG:
148             case STATE_PRE_VERIFIED:
149             default:
150                 return false;
151         }
152     }
153 
154     /**
155      * Checks if a state considers the corresponding domain to be successfully verified. The domain
156      * verification agent may use this to determine whether or not to re-verify a domain.
157      */
isVerified(@omainVerificationState.State int state)158     static boolean isVerified(@DomainVerificationState.State int state) {
159         switch (state) {
160             case DomainVerificationState.STATE_SUCCESS:
161             case DomainVerificationState.STATE_APPROVED:
162             case DomainVerificationState.STATE_MIGRATED:
163             case DomainVerificationState.STATE_RESTORED:
164             case DomainVerificationState.STATE_SYS_CONFIG:
165             case DomainVerificationState.STATE_PRE_VERIFIED:
166                 return true;
167             case DomainVerificationState.STATE_NO_RESPONSE:
168             case DomainVerificationState.STATE_DENIED:
169             case DomainVerificationState.STATE_LEGACY_FAILURE:
170             default:
171                 return false;
172         }
173     }
174 
175     /**
176      * Checks if a state is modifiable by the domain verification agent. This is useful as the
177      * platform may add new state codes in newer versions, and older verification agents can use
178      * this method to determine if a state can be changed without having to be aware of what the new
179      * state means.
180      */
isModifiable(@omainVerificationState.State int state)181     static boolean isModifiable(@DomainVerificationState.State int state) {
182         switch (state) {
183             case DomainVerificationState.STATE_NO_RESPONSE:
184             case DomainVerificationState.STATE_SUCCESS:
185             case DomainVerificationState.STATE_MIGRATED:
186             case DomainVerificationState.STATE_RESTORED:
187             case DomainVerificationState.STATE_LEGACY_FAILURE:
188             case DomainVerificationState.STATE_PRE_VERIFIED:
189                 return true;
190             case DomainVerificationState.STATE_APPROVED:
191             case DomainVerificationState.STATE_DENIED:
192             case DomainVerificationState.STATE_SYS_CONFIG:
193                 return false;
194             default:
195                 return state >= DomainVerificationState.STATE_FIRST_VERIFIER_DEFINED;
196         }
197     }
198 
199     /**
200      * Whether the state is migrated when updating a package. Generally this is only for states
201      * that maintain verification state or were set by an explicit user or developer action.
202      */
shouldMigrate(@tate int state)203     static boolean shouldMigrate(@State int state) {
204         switch (state) {
205             case STATE_SUCCESS:
206             case STATE_MIGRATED:
207             case STATE_RESTORED:
208             case STATE_APPROVED:
209             case STATE_DENIED:
210             case STATE_PRE_VERIFIED:
211                 return true;
212             case STATE_NO_RESPONSE:
213             case STATE_LEGACY_FAILURE:
214             case STATE_SYS_CONFIG:
215             case STATE_FIRST_VERIFIER_DEFINED:
216             default:
217                 return false;
218         }
219     }
220 
221     @DomainVerificationInfo.State
convertToInfoState(@tate int internalState)222     static int convertToInfoState(@State int internalState) {
223         if (internalState >= STATE_FIRST_VERIFIER_DEFINED) {
224             return internalState;
225         } else if (internalState == STATE_NO_RESPONSE) {
226             return DomainVerificationInfo.STATE_NO_RESPONSE;
227         } else if (internalState == STATE_SUCCESS) {
228             return DomainVerificationInfo.STATE_SUCCESS;
229         } else if (!isModifiable(internalState)) {
230             return DomainVerificationInfo.STATE_UNMODIFIABLE;
231         } else if (isVerified(internalState)) {
232             return DomainVerificationInfo.STATE_MODIFIABLE_VERIFIED;
233         } else {
234             return DomainVerificationInfo.STATE_MODIFIABLE_UNVERIFIED;
235         }
236     }
237 }
238