From 1aed7889c05bf9a9d93b506313e8c7f8a06442a1 Mon Sep 17 00:00:00 2001 From: Benjamin Miller Date: Tue, 15 Aug 2017 18:04:20 +0200 Subject: [PATCH] Docs: Javadoc comment fixups for secure passcode reset methods. Exceptions corrected for methods and cross references linked up. Clarification about resetPassword() and work profiles. Staged at: go/dac-stage/reference/android/app/admin/DevicePolicyManager.html Test: make ds-docs with output staged and visually checked in DevicePolicyManager page Bug: 38026339 Change-Id: I3346144193061fad7988c92e0d4be4b341ef7410 --- .../app/admin/DevicePolicyManager.java | 37 ++++++++++--------- 1 file changed, 19 insertions(+), 18 deletions(-) diff --git a/core/java/android/app/admin/DevicePolicyManager.java b/core/java/android/app/admin/DevicePolicyManager.java index d8da8c5bee824..32a64b0336d9a 100644 --- a/core/java/android/app/admin/DevicePolicyManager.java +++ b/core/java/android/app/admin/DevicePolicyManager.java @@ -2707,13 +2707,14 @@ public class DevicePolicyManager { } /** - * Flag for {@link #resetPassword}: don't allow other admins to change - * the password again until the user has entered it. + * Flag for {@link #resetPasswordWithToken} and {@link #resetPassword}: don't allow other admins + * to change the password again until the user has entered it. */ public static final int RESET_PASSWORD_REQUIRE_ENTRY = 0x0001; /** - * Flag for {@link #resetPassword}: don't ask for user credentials on device boot. + * Flag for {@link #resetPasswordWithToken} and {@link #resetPassword}: don't ask for user + * credentials on device boot. * If the flag is set, the device can be booted without asking for user password. * The absence of this flag does not change the current boot requirements. This flag * can be set by the device owner only. If the app is not the device owner, the flag @@ -2723,8 +2724,8 @@ public class DevicePolicyManager { public static final int RESET_PASSWORD_DO_NOT_ASK_CREDENTIALS_ON_BOOT = 0x0002; /** - * Force a new device unlock password (the password needed to access the entire device, not for - * individual accounts) on the user. This takes effect immediately. + * Force a new password for device unlock (the password needed to access the entire device) or + * the work profile challenge on the current user. This takes effect immediately. *

* For device owner and profile owners targeting SDK level * {@link android.os.Build.VERSION_CODES#O} or above, this API is no longer available and will @@ -2762,7 +2763,6 @@ public class DevicePolicyManager { * @throws SecurityException if the calling application does not own an active administrator * that uses {@link DeviceAdminInfo#USES_POLICY_RESET_PASSWORD} * @throws IllegalStateException if the calling user is locked or has a managed profile. - * @throws IllegalArgumentException if the password does not meet system requirements. */ public boolean resetPassword(String password, int flags) { throwIfParentInstance("resetPassword"); @@ -2804,8 +2804,8 @@ public class DevicePolicyManager { * @param token a secure token a least 32-byte long, which must be generated by a * cryptographically strong random number generator. * @return true if the operation is successful, false otherwise. + * @throws SecurityException if admin is not a device or profile owner. * @throws IllegalArgumentException if the supplied token is invalid. - * @throws SecurityException */ public boolean setResetPasswordToken(ComponentName admin, byte[] token) { throwIfParentInstance("setResetPasswordToken"); @@ -2824,6 +2824,7 @@ public class DevicePolicyManager { * * @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. */ public boolean clearResetPasswordToken(ComponentName admin) { throwIfParentInstance("clearResetPasswordToken"); @@ -2842,6 +2843,7 @@ public class DevicePolicyManager { * * @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. * @throws IllegalStateException if no token has been set. */ public boolean isResetPasswordTokenActive(ComponentName admin) { @@ -2867,24 +2869,23 @@ public class DevicePolicyManager { * The given password must be sufficient for the current password quality and length constraints * as returned by {@link #getPasswordQuality(ComponentName)} and * {@link #getPasswordMinimumLength(ComponentName)}; if it does not meet these constraints, then - * it will be rejected and false returned. Note that the password may be a stronger quality - * (containing alphanumeric characters when the requested quality is only numeric), in which - * case the currently active quality will be increased to match. + * it will be rejected and false returned. Note that the password may be a stronger quality, for + * example, a password containing alphanumeric characters when the requested quality is only + * numeric. *

- * Calling with a null or empty password will clear any existing PIN, pattern or password if the - * current password constraints allow it. + * Calling with a {@code null} or empty password will clear any existing PIN, pattern or + * password if the current password constraints allow it. * * @param admin Which {@link DeviceAdminReceiver} this request is associated with. - * @param password The new password for the user. Null or empty clears the password. - * @param token the password reset token previously provisioned by #setResetPasswordToken. + * @param password The new password for the user. {@code null} or empty clears the password. + * @param token the password reset token previously provisioned by + * {@link #setResetPasswordToken}. * @param flags May be 0 or combination of {@link #RESET_PASSWORD_REQUIRE_ENTRY} and - * {@link #RESET_PASSWORD_DO_NOT_ASK_CREDENTIALS_ON_BOOT}. + * {@link #RESET_PASSWORD_DO_NOT_ASK_CREDENTIALS_ON_BOOT}. * @return Returns true if the password was applied, or false if it is not acceptable for the * current constraints. - * @throws SecurityException if the calling application does not own an active administrator - * that uses {@link DeviceAdminInfo#USES_POLICY_RESET_PASSWORD} + * @throws SecurityException if admin is not a device or profile owner. * @throws IllegalStateException if the provided token is not valid. - * @throws IllegalArgumentException if the password does not meet system requirements. */ public boolean resetPasswordWithToken(@NonNull ComponentName admin, String password, byte[] token, int flags) {