1 /* 2 * Copyright (C) 2018 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 com.android.internal.widget; 18 19 import android.annotation.IntDef; 20 import android.annotation.Nullable; 21 import android.annotation.UserIdInt; 22 import android.app.admin.PasswordMetrics; 23 24 import java.lang.annotation.Retention; 25 import java.lang.annotation.RetentionPolicy; 26 /** 27 * LockSettingsService local system service interface. 28 * 29 * @hide Only for use within the system server. 30 */ 31 public abstract class LockSettingsInternal { 32 /** ErrorCode for armRebootEscrow failures. **/ 33 @IntDef(prefix = {"ARM_REBOOT_ERROR_"}, value = { 34 ARM_REBOOT_ERROR_NONE, 35 ARM_REBOOT_ERROR_UNSPECIFIED, 36 ARM_REBOOT_ERROR_ESCROW_NOT_READY, 37 ARM_REBOOT_ERROR_NO_PROVIDER, 38 ARM_REBOOT_ERROR_PROVIDER_MISMATCH, 39 ARM_REBOOT_ERROR_NO_ESCROW_KEY, 40 ARM_REBOOT_ERROR_KEYSTORE_FAILURE, 41 ARM_REBOOT_ERROR_STORE_ESCROW_KEY, 42 }) 43 @Retention(RetentionPolicy.SOURCE) 44 public @interface ArmRebootEscrowErrorCode {} 45 46 public static final int ARM_REBOOT_ERROR_NONE = 0; 47 public static final int ARM_REBOOT_ERROR_UNSPECIFIED = 1; 48 public static final int ARM_REBOOT_ERROR_ESCROW_NOT_READY = 2; 49 public static final int ARM_REBOOT_ERROR_NO_PROVIDER = 3; 50 public static final int ARM_REBOOT_ERROR_PROVIDER_MISMATCH = 4; 51 public static final int ARM_REBOOT_ERROR_NO_ESCROW_KEY = 5; 52 public static final int ARM_REBOOT_ERROR_KEYSTORE_FAILURE = 6; 53 public static final int ARM_REBOOT_ERROR_STORE_ESCROW_KEY = 7; 54 // TODO(b/183140900) split store escrow key errors into detailed ones. 55 56 /** 57 * This is called when Weaver is guaranteed to be available (if the device supports Weaver). 58 * It does any synthetic password related work that was delayed from earlier in the boot. 59 */ onThirdPartyAppsStarted()60 public abstract void onThirdPartyAppsStarted(); 61 62 /** 63 * Creates the locksettings state for a new user. 64 * <p> 65 * This includes creating a synthetic password and protecting it with an empty LSKF. 66 * 67 * @param userId the ID of the new user 68 * @param userSerialNumber the serial number of the new user 69 */ createNewUser(@serIdInt int userId, int userSerialNumber)70 public abstract void createNewUser(@UserIdInt int userId, int userSerialNumber); 71 72 /** 73 * Removes the locksettings state for the given user. 74 * <p> 75 * This includes removing the user's synthetic password and any protectors that are protecting 76 * it. 77 * 78 * @param userId the ID of the user being removed 79 */ removeUser(@serIdInt int userId)80 public abstract void removeUser(@UserIdInt int userId); 81 82 /** 83 * Create an escrow token for the current user, which can later be used to unlock FBE 84 * or change user password. 85 * 86 * After adding, if the user currently has lockscreen password, they will need to perform a 87 * confirm credential operation in order to activate the token for future use. 88 * Once the token is activated, the callback that is passed here is called. If the user 89 * has no secure lockscreen, then the token is activated immediately. 90 * 91 * @return a unique 64-bit token handle which is needed to refer to this token later. 92 */ addEscrowToken(byte[] token, int userId, LockPatternUtils.EscrowTokenStateChangeCallback callback)93 public abstract long addEscrowToken(byte[] token, int userId, 94 LockPatternUtils.EscrowTokenStateChangeCallback callback); 95 96 /** 97 * Remove an escrow token. 98 * 99 * @return true if the given handle refers to a valid token previously returned from 100 * {@link #addEscrowToken}, whether it's active or not. return false otherwise. 101 */ removeEscrowToken(long handle, int userId)102 public abstract boolean removeEscrowToken(long handle, int userId); 103 104 /** 105 * Check if the given escrow token is active or not. Only active token can be used to call 106 * {@link #setLockCredentialWithToken} and {@link #unlockUserWithToken} 107 */ isEscrowTokenActive(long handle, int userId)108 public abstract boolean isEscrowTokenActive(long handle, int userId); 109 110 /** 111 * Set the lock credential. 112 * 113 * @return true if password is set. 114 */ setLockCredentialWithToken(LockscreenCredential credential, long tokenHandle, byte[] token, int userId)115 public abstract boolean setLockCredentialWithToken(LockscreenCredential credential, 116 long tokenHandle, byte[] token, int userId); 117 unlockUserWithToken(long tokenHandle, byte[] token, int userId)118 public abstract boolean unlockUserWithToken(long tokenHandle, byte[] token, int userId); 119 120 /** 121 * Returns PasswordMetrics object corresponding to the given user's lockscreen password. 122 * If the user has a password but its metrics isn't known yet (for example if the device 123 * has not been unlocked since boot), this method will return {@code null}. 124 * If the user has no password, a default PasswordMetrics (PASSWORD_QUALITY_UNSPECIFIED) 125 * will be returned. 126 * 127 * Calling this method on a managed profile user with unified challenge is undefined. 128 * 129 * @param userHandle the user for whom to provide metrics. 130 * @return the user password metrics. 131 */ getUserPasswordMetrics(int userHandle)132 public abstract @Nullable PasswordMetrics getUserPasswordMetrics(int userHandle); 133 134 /** 135 * Prepare for reboot escrow. This triggers the strong auth to be required. After the escrow 136 * is complete as indicated by calling to the listener registered with {@link 137 * #setRebootEscrowListener}, then {@link #armRebootEscrow()} should be called before 138 * rebooting to apply the update. 139 */ prepareRebootEscrow()140 public abstract boolean prepareRebootEscrow(); 141 142 /** 143 * Registers a listener for when the RebootEscrow HAL has stored its data needed for rebooting 144 * for an OTA. 145 * 146 * @see RebootEscrowListener 147 * @param listener 148 */ setRebootEscrowListener(RebootEscrowListener listener)149 public abstract void setRebootEscrowListener(RebootEscrowListener listener); 150 151 /** 152 * Requests that any data needed for rebooting is cleared from the RebootEscrow HAL. 153 */ clearRebootEscrow()154 public abstract boolean clearRebootEscrow(); 155 156 /** 157 * Should be called immediately before rebooting for an update. This depends on {@link 158 * #prepareRebootEscrow()} having been called and the escrow completing. 159 * 160 * @return ARM_ERROR_NONE if the arming worked 161 */ armRebootEscrow()162 public abstract @ArmRebootEscrowErrorCode int armRebootEscrow(); 163 164 165 /** 166 * Refreshes pending strong auth timeout with the latest admin requirement set by device policy. 167 */ refreshStrongAuthTimeout(int userId)168 public abstract void refreshStrongAuthTimeout(int userId); 169 170 /** 171 * Register a LockSettingsStateListener 172 * @param listener The listener to be registered 173 */ registerLockSettingsStateListener(LockSettingsStateListener listener)174 public abstract void registerLockSettingsStateListener(LockSettingsStateListener listener); 175 176 /** 177 * Unregister a LockSettingsStateListener 178 * @param listener The listener to be unregistered 179 */ unregisterLockSettingsStateListener(LockSettingsStateListener listener)180 public abstract void unregisterLockSettingsStateListener(LockSettingsStateListener listener); 181 } 182