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