Donate to e Foundation | Murena handsets with /e/OS | Own a part of Murena! Learn more

Commit cef704e1 authored by Lenka Trochtova's avatar Lenka Trochtova
Browse files

Improve documentation of secure lock screen feature. 

Add more a specific description of what methods do when the
secure lock screen feature is not supported by the device.

Bug: 123270501
Test: make

Change-Id: Ib6c16f421cf3dc60b0f0cb0c6335c6dc35ac7ece
parent 3e4cc422

core/java/android/app/admin/DevicePolicyManager.java

+48 −4
Original line number Diff line number Diff line
@@ -59,7 +59,6 @@ import android.os.Build; 
import android.os.Bundle;

import android.os.ParcelFileDescriptor;

import android.os.Parcelable;

import android.os.ParcelableException;

import android.os.PersistableBundle;

import android.os.Process;

import android.os.RemoteCallback;
@@ -3154,7 +3153,7 @@ public class DevicePolicyManager { 
     * {@link #PASSWORD_QUALITY_ALPHANUMERIC} with {@link #setPasswordQuality}.

     * <p>

     * On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password is always treated as empty.

     * password history length is always 0.

     * <p>

     * The calling device admin must have requested

     * {@link DeviceAdminInfo#USES_POLICY_LIMIT_PASSWORD} to be able to call this method; if it has
@@ -3192,6 +3191,9 @@ public class DevicePolicyManager { 
     * <p>

     * To disable password expiration, a value of 0 may be used for timeout.

     * <p>

     * On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password expiration is always disabled.

     * <p>

     * The calling device admin must have requested

     * {@link DeviceAdminInfo#USES_POLICY_EXPIRE_PASSWORD} to be able to call this method; if it has

     * not, a security exception will be thrown.
@@ -3231,6 +3233,9 @@ public class DevicePolicyManager { 
     * returned by {@link #getParentProfileInstance(ComponentName)} in order to retrieve

     * restrictions on the parent profile.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password expiration is always disabled and this method always returns 0.

     *

     * @param admin The name of the admin component to check, or {@code null} to aggregate all admins.

     * @return The timeout for the given admin or the minimum of all timeouts

     */
@@ -3256,6 +3261,9 @@ public class DevicePolicyManager { 
     * returned by {@link #getParentProfileInstance(ComponentName)} in order to retrieve

     * the password expiration for the parent profile.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password expiration is always disabled and this method always returns 0.

     *

     * @param admin The name of the admin component to check, or {@code null} to aggregate all admins.

     * @return The password expiration time, in milliseconds since epoch.

     */
@@ -3280,6 +3288,9 @@ public class DevicePolicyManager { 
     * returned by {@link #getParentProfileInstance(ComponentName)} in order to retrieve

     * restrictions on the parent profile.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password history length is always 0.

     *

     * @param admin The name of the admin component to check, or {@code null} to aggregate

     * all admins.

     * @return The length of the password history
@@ -3307,7 +3318,7 @@ public class DevicePolicyManager { 
     * Return the maximum password length that the device supports for a

     * particular password quality.

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password is always empty.

     * password is always empty and this method always returns 0.

     * @param quality The quality being interrogated.

     * @return Returns the maximum length that the user can enter.

     */
@@ -3363,7 +3374,7 @@ public class DevicePolicyManager { 
     * #getParentProfileInstance}.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password is always treated as empty.

     * password is always empty and this method returns {@link #PASSWORD_COMPLEXITY_NONE}.

     *

     * @throws IllegalStateException if the user is not unlocked.

     * @throws SecurityException if the calling application does not have the permission
@@ -3438,6 +3449,8 @@ public class DevicePolicyManager { 
     * <p>

     * The calling device admin must have requested {@link DeviceAdminInfo#USES_POLICY_WATCH_LOGIN}

     * to be able to call this method; if it has not, a security exception will be thrown.

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password is always empty and this method always returns 0.

     *

     * @return The number of times user has entered an incorrect password since the last correct

     *         password entry.
@@ -3504,6 +3517,8 @@ public class DevicePolicyManager { 
     * This method can be called on the {@link DevicePolicyManager} instance returned by

     * {@link #getParentProfileInstance(ComponentName)} in order to set a value on the parent

     * profile.

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password is always empty and this method has no effect - i.e. the policy is not set.

     *

     * @param admin Which {@link DeviceAdminReceiver} this request is associated with.

     * @param num The number of failed password attempts at which point the device or profile will
@@ -3533,6 +3548,10 @@ public class DevicePolicyManager { 
     * returned by {@link #getParentProfileInstance(ComponentName)} in order to retrieve

     * the value for the parent profile.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * password is always empty and this method returns a default value (0) indicating that the

     * policy is not set.

     *

     * @param admin The name of the admin component to check, or {@code null} to aggregate

     * all admins.

     */
@@ -3620,6 +3639,8 @@ public class DevicePolicyManager { 
     * {@link android.os.Build.VERSION_CODES#N} and later for managed profiles, or for device admins

     * that are not device owner or profile owner.  Once set, the password cannot be changed to null

     * or empty except by these admins.</em>

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, this

     * methods does nothing.

     * <p>

     * The calling device admin must have requested

     * {@link DeviceAdminInfo#USES_POLICY_RESET_PASSWORD} to be able to call this method; if it has
@@ -3670,6 +3691,8 @@ public class DevicePolicyManager { 
     * will be stored on your server and who will need access to them. Tokens may be the subject of

     * legal access requests.

     * </em>

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, the

     * reset token is not set and this method returns false.

     *

     * @param admin Which {@link DeviceAdminReceiver} this request is associated with.

     * @param token a secure token a least 32-byte long, which must be generated by a
@@ -3694,6 +3717,10 @@ public class DevicePolicyManager { 
    /**

     * Called by a profile or device owner to revoke the current password reset token.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, this

     * method has no effect - the reset token should not have been set in the first place - and

     * false is returned.

     *

     * @param admin Which {@link DeviceAdminReceiver} this request is associated with.

     * @return true if the operation is successful, false otherwise.

     * @throws SecurityException if admin is not a device or profile owner.
@@ -3714,6 +3741,9 @@ public class DevicePolicyManager { 
    /**

     * Called by a profile or device owner to check if the current reset password token is active.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature,

     * false is always returned.

     *

     * @param admin Which {@link DeviceAdminReceiver} this request is associated with.

     * @return true if the token is active, false otherwise.

     * @throws SecurityException if admin is not a device or profile owner.
@@ -3749,6 +3779,8 @@ public class DevicePolicyManager { 
     * <p>

     * Calling with a {@code null} or empty password will clear any existing PIN, pattern or

     * password if the current password constraints allow it.

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature,

     * calling this methods has no effect - the password is always empty - and false is returned.

     *

     * @param admin Which {@link DeviceAdminReceiver} this request is associated with.

     * @param password The new password for the user. {@code null} or empty clears the password.
@@ -3856,6 +3888,9 @@ public class DevicePolicyManager { 
     * {@link #getParentProfileInstance(ComponentName)} in order to set restrictions on the parent

     * profile.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature,

     * calling this methods has no effect - i.e. the timeout is not set.

     *

     * @param admin Which {@link DeviceAdminReceiver} this request is associated with.

     * @param timeoutMs The new timeout in milliseconds, after which the user will have to unlock

     *         with strong authentication method. A value of 0 means the admin is not participating
@@ -3888,6 +3923,9 @@ public class DevicePolicyManager { 
     * returned by {@link #getParentProfileInstance(ComponentName)} in order to retrieve

     * restrictions on the parent profile.

     *

     * <p>On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature,

     * 0 is returned to indicate that no timeout is configured.

     *

     * @param admin The name of the admin component to check, or {@code null} to aggregate

     *         across all participating admins.

     * @return The timeout in milliseconds or 0 if not configured for the provided admin.
@@ -6618,6 +6656,9 @@ public class DevicePolicyManager { 
     * This method can be called on the {@link DevicePolicyManager} instance returned by

     * {@link #getParentProfileInstance(ComponentName)} in order to set the configuration for

     * the parent profile.

     * <p>

     * On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, calling

     * this method has no effect - no trust agent configuration will be set.

     *

     * @param admin Which {@link DeviceAdminReceiver} this request is associated with.

     * @param target Component name of the agent to be configured.
@@ -6647,6 +6688,9 @@ public class DevicePolicyManager { 
     * This method can be called on the {@link DevicePolicyManager} instance returned by

     * {@link #getParentProfileInstance(ComponentName)} in order to retrieve the configuration set

     * on the parent profile.

     * <p>

     * On devices not supporting {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature, null is

     * always returned.

     *

     * @param admin Which {@link DeviceAdminReceiver} this request is associated with. If null,

     * this function returns a list of configurations for all admins that declare

services/devicepolicy/java/com/android/server/devicepolicy/DevicePolicyManagerService.java

+6 −2
Original line number Diff line number Diff line
@@ -172,7 +172,6 @@ import android.os.Handler; 
import android.os.IBinder;

import android.os.Looper;

import android.os.ParcelFileDescriptor;

import android.os.ParcelableException;

import android.os.PersistableBundle;

import android.os.PowerManager;

import android.os.PowerManagerInternal;
@@ -5338,9 +5337,14 @@ public class DevicePolicyManagerService extends BaseIDevicePolicyManager { 
     */

    @Override

    public long getRequiredStrongAuthTimeout(ComponentName who, int userId, boolean parent) {

        if (!mHasFeature || !mLockPatternUtils.hasSecureLockScreen()) {

        if (!mHasFeature) {

            return DevicePolicyManager.DEFAULT_STRONG_AUTH_TIMEOUT_MS;

        }

        if (!mLockPatternUtils.hasSecureLockScreen()) {

            // No strong auth timeout on devices not supporting the

            // {@link PackageManager#FEATURE_SECURE_LOCK_SCREEN} feature

            return 0;

        }

        enforceFullCrossUsersPermission(userId);

        synchronized (getLockObject()) {

            if (who != null) {