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 * Unlocks the credential-encrypted storage for the given user if the user is not secured, i.e. 64 * doesn't have an LSKF. 65 * <p> 66 * This doesn't throw an exception on failure; whether the storage has been unlocked can be 67 * determined by {@link StorageManager#isUserKeyUnlocked()}. 68 * 69 * @param userId the ID of the user whose storage to unlock 70 */ unlockUserKeyIfUnsecured(@serIdInt int userId)71 public abstract void unlockUserKeyIfUnsecured(@UserIdInt int userId); 72 73 /** 74 * Creates the locksettings state for a new user. 75 * <p> 76 * This includes creating a synthetic password and protecting it with an empty LSKF. 77 * 78 * @param userId the ID of the new user 79 * @param userSerialNumber the serial number of the new user 80 */ createNewUser(@serIdInt int userId, int userSerialNumber)81 public abstract void createNewUser(@UserIdInt int userId, int userSerialNumber); 82 83 /** 84 * Removes the locksettings state for the given user. 85 * <p> 86 * This includes removing the user's synthetic password and any protectors that are protecting 87 * it. 88 * 89 * @param userId the ID of the user being removed 90 */ removeUser(@serIdInt int userId)91 public abstract void removeUser(@UserIdInt int userId); 92 93 /** 94 * Create an escrow token for the current user, which can later be used to unlock FBE 95 * or change user password. 96 * 97 * After adding, if the user currently has lockscreen password, they will need to perform a 98 * confirm credential operation in order to activate the token for future use. 99 * Once the token is activated, the callback that is passed here is called. If the user 100 * has no secure lockscreen, then the token is activated immediately. 101 * 102 * @return a unique 64-bit token handle which is needed to refer to this token later. 103 */ addEscrowToken(byte[] token, int userId, LockPatternUtils.EscrowTokenStateChangeCallback callback)104 public abstract long addEscrowToken(byte[] token, int userId, 105 LockPatternUtils.EscrowTokenStateChangeCallback callback); 106 107 /** 108 * Remove an escrow token. 109 * 110 * @return true if the given handle refers to a valid token previously returned from 111 * {@link #addEscrowToken}, whether it's active or not. return false otherwise. 112 */ removeEscrowToken(long handle, int userId)113 public abstract boolean removeEscrowToken(long handle, int userId); 114 115 /** 116 * Check if the given escrow token is active or not. Only active token can be used to call 117 * {@link #setLockCredentialWithToken} and {@link #unlockUserWithToken} 118 */ isEscrowTokenActive(long handle, int userId)119 public abstract boolean isEscrowTokenActive(long handle, int userId); 120 121 /** 122 * Set the lock credential. 123 * 124 * @return true if password is set. 125 */ setLockCredentialWithToken(LockscreenCredential credential, long tokenHandle, byte[] token, int userId)126 public abstract boolean setLockCredentialWithToken(LockscreenCredential credential, 127 long tokenHandle, byte[] token, int userId); 128 unlockUserWithToken(long tokenHandle, byte[] token, int userId)129 public abstract boolean unlockUserWithToken(long tokenHandle, byte[] token, int userId); 130 131 /** 132 * Returns PasswordMetrics object corresponding to the given user's lockscreen password. 133 * If the user has a password but its metrics isn't known yet (for example if the device 134 * has not been unlocked since boot), this method will return {@code null}. 135 * If the user has no password, a default PasswordMetrics (PASSWORD_QUALITY_UNSPECIFIED) 136 * will be returned. 137 * 138 * Calling this method on a managed profile user with unified challenge is undefined. 139 * 140 * @param userHandle the user for whom to provide metrics. 141 * @return the user password metrics. 142 */ getUserPasswordMetrics(int userHandle)143 public abstract @Nullable PasswordMetrics getUserPasswordMetrics(int userHandle); 144 145 /** 146 * Prepare for reboot escrow. This triggers the strong auth to be required. After the escrow 147 * is complete as indicated by calling to the listener registered with {@link 148 * #setRebootEscrowListener}, then {@link #armRebootEscrow()} should be called before 149 * rebooting to apply the update. 150 */ prepareRebootEscrow()151 public abstract boolean prepareRebootEscrow(); 152 153 /** 154 * Registers a listener for when the RebootEscrow HAL has stored its data needed for rebooting 155 * for an OTA. 156 * 157 * @see RebootEscrowListener 158 * @param listener 159 */ setRebootEscrowListener(RebootEscrowListener listener)160 public abstract void setRebootEscrowListener(RebootEscrowListener listener); 161 162 /** 163 * Requests that any data needed for rebooting is cleared from the RebootEscrow HAL. 164 */ clearRebootEscrow()165 public abstract boolean clearRebootEscrow(); 166 167 /** 168 * Should be called immediately before rebooting for an update. This depends on {@link 169 * #prepareRebootEscrow()} having been called and the escrow completing. 170 * 171 * @return ARM_ERROR_NONE if the arming worked 172 */ armRebootEscrow()173 public abstract @ArmRebootEscrowErrorCode int armRebootEscrow(); 174 175 176 /** 177 * Refreshes pending strong auth timeout with the latest admin requirement set by device policy. 178 */ refreshStrongAuthTimeout(int userId)179 public abstract void refreshStrongAuthTimeout(int userId); 180 } 181