1/* 2 * Copyright (C) 2017 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 */ 16package android.service.autofill; 17 18import android.annotation.CallSuper; 19import android.annotation.NonNull; 20import android.annotation.Nullable; 21import android.os.RemoteException; 22import android.provider.Settings; 23 24import com.android.internal.os.HandlerCaller; 25import android.annotation.SdkConstant; 26import android.app.Service;import android.content.Intent; 27import android.os.CancellationSignal; 28import android.os.IBinder; 29import android.os.ICancellationSignal; 30import android.os.Looper; 31import android.util.Log; 32import android.view.View; 33import android.view.ViewStructure; 34import android.view.autofill.AutofillId; 35import android.view.autofill.AutofillManager; 36import android.view.autofill.AutofillValue; 37 38import com.android.internal.os.SomeArgs; 39 40/** 41 * An {@code AutofillService} is a service used to automatically fill the contents of the screen 42 * on behalf of a given user - for more information about autofill, read 43 * <a href="{@docRoot}preview/features/autofill.html">Autofill Framework</a>. 44 * 45 * <p>An {@code AutofillService} is only bound to the Android System for autofill purposes if: 46 * <ol> 47 * <li>It requires the {@code android.permission.BIND_AUTOFILL_SERVICE} permission in its 48 * manifest. 49 * <li>The user explicitly enables it using Android Settings (the 50 * {@link Settings#ACTION_REQUEST_SET_AUTOFILL_SERVICE} intent can be used to launch such 51 * Settings screen). 52 * </ol> 53 * 54 * <h3>Basic usage</h3> 55 * 56 * <p>The basic autofill process is defined by the workflow below: 57 * <ol> 58 * <li>User focus an editable {@link View}. 59 * <li>View calls {@link AutofillManager#notifyViewEntered(android.view.View)}. 60 * <li>A {@link ViewStructure} representing all views in the screen is created. 61 * <li>The Android System binds to the service and calls {@link #onConnected()}. 62 * <li>The service receives the view structure through the 63 * {@link #onFillRequest(FillRequest, CancellationSignal, FillCallback)}. 64 * <li>The service replies through {@link FillCallback#onSuccess(FillResponse)}. 65 * <li>The Android System calls {@link #onDisconnected()} and unbinds from the 66 * {@code AutofillService}. 67 * <li>The Android System displays an UI affordance with the options sent by the service. 68 * <li>The user picks an option. 69 * <li>The proper views are autofilled. 70 * </ol> 71 * 72 * <p>This workflow was designed to minimize the time the Android System is bound to the service; 73 * for each call, it: binds to service, waits for the reply, and unbinds right away. Furthermore, 74 * those calls are considered stateless: if the service needs to keep state between calls, it must 75 * do its own state management (keeping in mind that the service's process might be killed by the 76 * Android System when unbound; for example, if the device is running low in memory). 77 * 78 * <p>Typically, the 79 * {@link #onFillRequest(FillRequest, CancellationSignal, FillCallback)} will: 80 * <ol> 81 * <li>Parse the view structure looking for autofillable views (for example, using 82 * {@link android.app.assist.AssistStructure.ViewNode#getAutofillHints()}. 83 * <li>Match the autofillable views with the user's data. 84 * <li>Create a {@link Dataset} for each set of user's data that match those fields. 85 * <li>Fill the dataset(s) with the proper {@link AutofillId}s and {@link AutofillValue}s. 86 * <li>Add the dataset(s) to the {@link FillResponse} passed to 87 * {@link FillCallback#onSuccess(FillResponse)}. 88 * </ol> 89 * 90 * <p>For example, for a login screen with username and password views where the user only has one 91 * account in the service, the response could be: 92 * 93 * <pre class="prettyprint"> 94 * new FillResponse.Builder() 95 * .addDataset(new Dataset.Builder() 96 * .setValue(id1, AutofillValue.forText("homer"), createPresentation("homer")) 97 * .setValue(id2, AutofillValue.forText("D'OH!"), createPresentation("password for homer")) 98 * .build()) 99 * .build(); 100 * </pre> 101 * 102 * <p>But if the user had 2 accounts instead, the response could be: 103 * 104 * <pre class="prettyprint"> 105 * new FillResponse.Builder() 106 * .addDataset(new Dataset.Builder() 107 * .setValue(id1, AutofillValue.forText("homer"), createPresentation("homer")) 108 * .setValue(id2, AutofillValue.forText("D'OH!"), createPresentation("password for homer")) 109 * .build()) 110 * .addDataset(new Dataset.Builder() 111 * .setValue(id1, AutofillValue.forText("flanders"), createPresentation("flanders")) 112 * .setValue(id2, AutofillValue.forText("OkelyDokelyDo"), createPresentation("password for flanders")) 113 * .build()) 114 * .build(); 115 * </pre> 116 * 117 * <p>If the service does not find any autofillable view in the view structure, it should pass 118 * {@code null} to {@link FillCallback#onSuccess(FillResponse)}; if the service encountered an error 119 * processing the request, it should call {@link FillCallback#onFailure(CharSequence)}. For 120 * performance reasons, it's paramount that the service calls either 121 * {@link FillCallback#onSuccess(FillResponse)} or {@link FillCallback#onFailure(CharSequence)} for 122 * each {@link #onFillRequest(FillRequest, CancellationSignal, FillCallback)} received - if it 123 * doesn't, the request will eventually time out and be discarded by the Android System. 124 * 125 * <h3>Saving user data</h3> 126 * 127 * <p>If the service is also interested on saving the data filled by the user, it must set a 128 * {@link SaveInfo} object in the {@link FillResponse}. See {@link SaveInfo} for more details and 129 * examples. 130 * 131 * <h3>User authentication</h3> 132 * 133 * <p>The service can provide an extra degree of security by requiring the user to authenticate 134 * before an app can be autofilled. The authentication is typically required in 2 scenarios: 135 * <ul> 136 * <li>To unlock the user data (for example, using a master password or fingerprint 137 * authentication) - see 138 * {@link FillResponse.Builder#setAuthentication(AutofillId[], android.content.IntentSender, android.widget.RemoteViews)}. 139 * <li>To unlock a specific dataset (for example, by providing a CVC for a credit card) - see 140 * {@link Dataset.Builder#setAuthentication(android.content.IntentSender)}. 141 * </ul> 142 * 143 * <p>When using authentication, it is recommended to encrypt only the sensitive data and leave 144 * labels unencrypted, so they can be used on presentation views. For example, if the user has a 145 * home and a work address, the {@code Home} and {@code Work} labels should be stored unencrypted 146 * (since they don't have any sensitive data) while the address data per se could be stored in an 147 * encrypted storage. Then when the user chooses the {@code Home} dataset, the platform starts 148 * the authentication flow, and the service can decrypt the sensitive data. 149 * 150 * <p>The authentication mechanism can also be used in scenarios where the service needs multiple 151 * steps to determine the datasets that can fill a screen. For example, when autofilling a financial 152 * app where the user has accounts for multiple banks, the workflow could be: 153 * 154 * <ol> 155 * <li>The first {@link FillResponse} contains datasets with the credentials for the financial 156 * app, plus a "fake" dataset whose presentation says "Tap here for banking apps credentials". 157 * <li>When the user selects the fake dataset, the service displays a dialog with available 158 * banking apps. 159 * <li>When the user select a banking app, the service replies with a new {@link FillResponse} 160 * containing the datasets for that bank. 161 * </ol> 162 * 163 * <p>Another example of multiple-steps dataset selection is when the service stores the user 164 * credentials in "vaults": the first response would contain fake datasets with the vault names, 165 * and the subsequent response would contain the app credentials stored in that vault. 166 * 167 * <h3>Data partitioning</h3> 168 * 169 * <p>The autofillable views in a screen should be grouped in logical groups called "partitions". 170 * Typical partitions are: 171 * <ul> 172 * <li>Credentials (username/email address, password). 173 * <li>Address (street, city, state, zip code, etc). 174 * <li>Payment info (credit card number, expiration date, and verification code). 175 * </ul> 176 * <p>For security reasons, when a screen has more than one partition, it's paramount that the 177 * contents of a dataset do not spawn multiple partitions, specially when one of the partitions 178 * contains data that is not specific to the application being autofilled. For example, a dataset 179 * should not contain fields for username, password, and credit card information. The reason for 180 * this rule is that a malicious app could draft a view structure where the credit card fields 181 * are not visible, so when the user selects a dataset from the username UI, the credit card info is 182 * released to the application without the user knowledge. Similar, it's recommended to always 183 * protect a dataset that contains sensitive information by requiring dataset authentication 184 * (see {@link Dataset.Builder#setAuthentication(android.content.IntentSender)}). 185 * 186 * <p>When the service detects that a screen have multiple partitions, it should return a 187 * {@link FillResponse} with just the datasets for the partition that originated the request (i.e., 188 * the partition that has the {@link android.app.assist.AssistStructure.ViewNode} whose 189 * {@link android.app.assist.AssistStructure.ViewNode#isFocused()} returns {@code true}); then if 190 * the user selects a field from a different partition, the Android System will make another 191 * {@link #onFillRequest(FillRequest, CancellationSignal, FillCallback)} call for that partition, 192 * and so on. 193 * 194 * <p>Notice that when the user autofill a partition with the data provided by the service and the 195 * user did not change these fields, the autofilled value is sent back to the service in the 196 * subsequent calls (and can be obtained by calling 197 * {@link android.app.assist.AssistStructure.ViewNode#getAutofillValue()}). This is useful in the 198 * cases where the service must create datasets for a partition based on the choice made in a 199 * previous partition. For example, the 1st response for a screen that have credentials and address 200 * partitions could be: 201 * 202 * <pre class="prettyprint"> 203 * new FillResponse.Builder() 204 * .addDataset(new Dataset.Builder() // partition 1 (credentials) 205 * .setValue(id1, AutofillValue.forText("homer"), createPresentation("homer")) 206 * .setValue(id2, AutofillValue.forText("D'OH!"), createPresentation("password for homer")) 207 * .build()) 208 * .addDataset(new Dataset.Builder() // partition 1 (credentials) 209 * .setValue(id1, AutofillValue.forText("flanders"), createPresentation("flanders")) 210 * .setValue(id2, AutofillValue.forText("OkelyDokelyDo"), createPresentation("password for flanders")) 211 * .build()) 212 * .setSaveInfo(new SaveInfo.Builder(SaveInfo.SAVE_DATA_TYPE_PASSWORD, 213 * new AutofillId[] { id1, id2 }) 214 * .build()) 215 * .build(); 216 * </pre> 217 * 218 * <p>Then if the user selected {@code flanders}, the service would get a new 219 * {@link #onFillRequest(FillRequest, CancellationSignal, FillCallback)} call, with the values of 220 * the fields {@code id1} and {@code id2} prepopulated, so the service could then fetch the address 221 * for the Flanders account and return the following {@link FillResponse} for the address partition: 222 * 223 * <pre class="prettyprint"> 224 * new FillResponse.Builder() 225 * .addDataset(new Dataset.Builder() // partition 2 (address) 226 * .setValue(id3, AutofillValue.forText("744 Evergreen Terrace"), createPresentation("744 Evergreen Terrace")) // street 227 * .setValue(id4, AutofillValue.forText("Springfield"), createPresentation("Springfield")) // city 228 * .build()) 229 * .setSaveInfo(new SaveInfo.Builder(SaveInfo.SAVE_DATA_TYPE_PASSWORD | SaveInfo.SAVE_DATA_TYPE_ADDRESS, 230 * new AutofillId[] { id1, id2 }) // username and password 231 * .setOptionalIds(new AutofillId[] { id3, id4 }) // state and zipcode 232 * .build()) 233 * .build(); 234 * </pre> 235 * 236 * <p>When the service returns multiple {@link FillResponse}, the last one overrides the previous; 237 * that's why the {@link SaveInfo} in the 2nd request above has the info for both partitions. 238 * 239 * <h3>Ignoring views</h3> 240 * 241 * <p>If the service find views that cannot be autofilled (for example, a text field representing 242 * the response to a Captcha challenge), it should mark those views as ignored by 243 * calling {@link FillResponse.Builder#setIgnoredIds(AutofillId...)} so the system does not trigger 244 * a new {@link #onFillRequest(FillRequest, CancellationSignal, FillCallback)} when these views are 245 * focused. 246 */ 247public abstract class AutofillService extends Service { 248 private static final String TAG = "AutofillService"; 249 250 /** 251 * The {@link Intent} that must be declared as handled by the service. 252 * To be supported, the service must also require the 253 * {@link android.Manifest.permission#BIND_AUTOFILL_SERVICE} permission so 254 * that other applications can not abuse it. 255 */ 256 @SdkConstant(SdkConstant.SdkConstantType.SERVICE_ACTION) 257 public static final String SERVICE_INTERFACE = "android.service.autofill.AutofillService"; 258 259 /** 260 * Name under which a AutoFillService component publishes information about itself. 261 * This meta-data should reference an XML resource containing a 262 * <code><{@link 263 * android.R.styleable#AutofillService autofill-service}></code> tag. 264 * This is a a sample XML file configuring an AutoFillService: 265 * <pre> <autofill-service 266 * android:settingsActivity="foo.bar.SettingsActivity" 267 * . . . 268 * /></pre> 269 */ 270 public static final String SERVICE_META_DATA = "android.autofill"; 271 272 // Handler messages. 273 private static final int MSG_CONNECT = 1; 274 private static final int MSG_DISCONNECT = 2; 275 private static final int MSG_ON_FILL_REQUEST = 3; 276 private static final int MSG_ON_SAVE_REQUEST = 4; 277 278 private final IAutoFillService mInterface = new IAutoFillService.Stub() { 279 @Override 280 public void onConnectedStateChanged(boolean connected) { 281 if (connected) { 282 mHandlerCaller.obtainMessage(MSG_CONNECT).sendToTarget(); 283 } else { 284 mHandlerCaller.obtainMessage(MSG_DISCONNECT).sendToTarget(); 285 } 286 } 287 288 @Override 289 public void onFillRequest(FillRequest request, IFillCallback callback) { 290 ICancellationSignal transport = CancellationSignal.createTransport(); 291 try { 292 callback.onCancellable(transport); 293 } catch (RemoteException e) { 294 e.rethrowFromSystemServer(); 295 } 296 mHandlerCaller.obtainMessageOOO(MSG_ON_FILL_REQUEST, request, 297 CancellationSignal.fromTransport(transport), callback) 298 .sendToTarget(); 299 } 300 301 @Override 302 public void onSaveRequest(SaveRequest request, ISaveCallback callback) { 303 mHandlerCaller.obtainMessageOO(MSG_ON_SAVE_REQUEST, request, 304 callback).sendToTarget(); 305 } 306 }; 307 308 private final HandlerCaller.Callback mHandlerCallback = (msg) -> { 309 switch (msg.what) { 310 case MSG_CONNECT: { 311 onConnected(); 312 break; 313 } case MSG_ON_FILL_REQUEST: { 314 final SomeArgs args = (SomeArgs) msg.obj; 315 final FillRequest request = (FillRequest) args.arg1; 316 final CancellationSignal cancellation = (CancellationSignal) args.arg2; 317 final IFillCallback callback = (IFillCallback) args.arg3; 318 final FillCallback fillCallback = new FillCallback(callback, request.getId()); 319 args.recycle(); 320 onFillRequest(request, cancellation, fillCallback); 321 break; 322 } case MSG_ON_SAVE_REQUEST: { 323 final SomeArgs args = (SomeArgs) msg.obj; 324 final SaveRequest request = (SaveRequest) args.arg1; 325 final ISaveCallback callback = (ISaveCallback) args.arg2; 326 final SaveCallback saveCallback = new SaveCallback(callback); 327 args.recycle(); 328 onSaveRequest(request, saveCallback); 329 break; 330 } case MSG_DISCONNECT: { 331 onDisconnected(); 332 break; 333 } default: { 334 Log.w(TAG, "MyCallbacks received invalid message type: " + msg); 335 } 336 } 337 }; 338 339 private HandlerCaller mHandlerCaller; 340 341 @CallSuper 342 @Override 343 public void onCreate() { 344 super.onCreate(); 345 mHandlerCaller = new HandlerCaller(null, Looper.getMainLooper(), mHandlerCallback, true); 346 } 347 348 @Override 349 public final IBinder onBind(Intent intent) { 350 if (SERVICE_INTERFACE.equals(intent.getAction())) { 351 return mInterface.asBinder(); 352 } 353 Log.w(TAG, "Tried to bind to wrong intent: " + intent); 354 return null; 355 } 356 357 /** 358 * Called when the Android system connects to service. 359 * 360 * <p>You should generally do initialization here rather than in {@link #onCreate}. 361 */ 362 public void onConnected() { 363 } 364 365 /** 366 * Called by the Android system do decide if a screen can be autofilled by the service. 367 * 368 * <p>Service must call one of the {@link FillCallback} methods (like 369 * {@link FillCallback#onSuccess(FillResponse)} 370 * or {@link FillCallback#onFailure(CharSequence)}) 371 * to notify the result of the request. 372 * 373 * @param request the {@link FillRequest request} to handle. 374 * See {@link FillResponse} for examples of multiple-sections requests. 375 * @param cancellationSignal signal for observing cancellation requests. The system will use 376 * this to notify you that the fill result is no longer needed and you should stop 377 * handling this fill request in order to save resources. 378 * @param callback object used to notify the result of the request. 379 */ 380 public abstract void onFillRequest(@NonNull FillRequest request, 381 @NonNull CancellationSignal cancellationSignal, @NonNull FillCallback callback); 382 383 /** 384 * Called when user requests service to save the fields of a screen. 385 * 386 * <p>Service must call one of the {@link SaveCallback} methods (like 387 * {@link SaveCallback#onSuccess()} or {@link SaveCallback#onFailure(CharSequence)}) 388 * to notify the result of the request. 389 * 390 * <p><b>NOTE: </b>to retrieve the actual value of the field, the service should call 391 * {@link android.app.assist.AssistStructure.ViewNode#getAutofillValue()}; if it calls 392 * {@link android.app.assist.AssistStructure.ViewNode#getText()} or other methods, there is no 393 * guarantee such method will return the most recent value of the field. 394 * 395 * @param request the {@link SaveRequest request} to handle. 396 * See {@link FillResponse} for examples of multiple-sections requests. 397 * @param callback object used to notify the result of the request. 398 */ 399 public abstract void onSaveRequest(@NonNull SaveRequest request, 400 @NonNull SaveCallback callback); 401 402 /** 403 * Called when the Android system disconnects from the service. 404 * 405 * <p> At this point this service may no longer be an active {@link AutofillService}. 406 */ 407 public void onDisconnected() { 408 } 409 410 /** 411 * Gets the events that happened after the last 412 * {@link AutofillService#onFillRequest(FillRequest, android.os.CancellationSignal, FillCallback)} 413 * call. 414 * 415 * <p>This method is typically used to keep track of previous user actions to optimize further 416 * requests. For example, the service might return email addresses in alphabetical order by 417 * default, but change that order based on the address the user picked on previous requests. 418 * 419 * <p>The history is not persisted over reboots, and it's cleared every time the service 420 * replies to a {@link #onFillRequest(FillRequest, CancellationSignal, FillCallback)} by calling 421 * {@link FillCallback#onSuccess(FillResponse)} or {@link FillCallback#onFailure(CharSequence)} 422 * (if the service doesn't call any of these methods, the history will clear out after some 423 * pre-defined time). Hence, the service should call {@link #getFillEventHistory()} before 424 * finishing the {@link FillCallback}. 425 * 426 * @return The history or {@code null} if there are no events. 427 */ 428 @Nullable public final FillEventHistory getFillEventHistory() { 429 final AutofillManager afm = getSystemService(AutofillManager.class); 430 431 if (afm == null) { 432 return null; 433 } else { 434 return afm.getFillEventHistory(); 435 } 436 } 437} 438