OpenJDK / jdk / jdk10
changeset 25989:6a57ce3f21f1
7026255: Methods of Subject that throw SecurityException do not specify what permissions are required
Reviewed-by: xuelei
| author | mullan |
|---|---|
| date | Mon, 18 Aug 2014 08:45:08 -0400 |
| parents | 76e62811f63b |
| children | 1f781f80ea0a |
| files | jdk/src/share/classes/javax/security/auth/Subject.java |
| diffstat | 1 files changed, 95 insertions(+), 96 deletions(-) [+] |
line wrap: on
line diff
--- a/jdk/src/share/classes/javax/security/auth/Subject.java Fri Aug 15 12:28:58 2014 +0200 +++ b/jdk/src/share/classes/javax/security/auth/Subject.java Mon Aug 18 08:45:08 2014 -0400 @@ -182,21 +182,20 @@ * {@code AuthPermission("modifyPublicCredentials")}. * To modify the private credential Set, the caller must have * {@code AuthPermission("modifyPrivateCredentials")}. - * <p> * * @param readOnly true if the {@code Subject} is to be read-only, - * and false otherwise. <p> + * and false otherwise. * * @param principals the {@code Set} of Principals - * to be associated with this {@code Subject}. <p> + * to be associated with this {@code Subject}. * * @param pubCredentials the {@code Set} of public credentials - * to be associated with this {@code Subject}. <p> + * to be associated with this {@code Subject}. * * @param privCredentials the {@code Set} of private credentials * to be associated with this {@code Subject}. * - * @exception NullPointerException if the specified + * @throws NullPointerException if the specified * {@code principals}, {@code pubCredentials}, * or {@code privCredentials} are {@code null}, * or a null value exists within any of these three @@ -233,10 +232,11 @@ * Also, once a {@code Subject} is read-only, * it can not be reset to being writable again. * - * <p> - * - * @exception SecurityException if the caller does not have permission - * to set this {@code Subject} to be read-only. + * @throws SecurityException if a security manager is installed and the + * caller does not have an + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("setReadOnly")} permission to set this + * {@code Subject} to be read-only. */ public void setReadOnly() { java.lang.SecurityManager sm = System.getSecurityManager(); @@ -250,8 +250,6 @@ /** * Query whether this {@code Subject} is read-only. * - * <p> - * * @return true if this {@code Subject} is read-only, false otherwise. */ public boolean isReadOnly() { @@ -267,8 +265,6 @@ * In this situation, the most recent {@code Subject} associated * with the {@code AccessControlContext} is returned. * - * <p> - * * @param acc the {@code AccessControlContext} from which to retrieve * the {@code Subject}. * @@ -277,10 +273,13 @@ * if no {@code Subject} is associated * with the provided {@code AccessControlContext}. * - * @exception SecurityException if the caller does not have permission - * to get the {@code Subject}. <p> + * @throws SecurityException if a security manager is installed and the + * caller does not have an + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("getSubject")} permission to get the + * {@code Subject}. * - * @exception NullPointerException if the provided + * @throws NullPointerException if the provided * {@code AccessControlContext} is {@code null}. */ public static Subject getSubject(final AccessControlContext acc) { @@ -321,26 +320,27 @@ * passing it the provided {@code PrivilegedAction}, * as well as the newly constructed {@code AccessControlContext}. * - * <p> - * * @param subject the {@code Subject} that the specified * {@code action} will run as. This parameter - * may be {@code null}. <p> + * may be {@code null}. * * @param <T> the type of the value returned by the PrivilegedAction's * {@code run} method. * * @param action the code to be run as the specified - * {@code Subject}. <p> + * {@code Subject}. * * @return the value returned by the PrivilegedAction's * {@code run} method. * - * @exception NullPointerException if the {@code PrivilegedAction} - * is {@code null}. <p> + * @throws NullPointerException if the {@code PrivilegedAction} + * is {@code null}. * - * @exception SecurityException if the caller does not have permission - * to invoke this method. + * @throws SecurityException if a security manager is installed and the + * caller does not have an + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("doAs")} permission to invoke this + * method. */ public static <T> T doAs(final Subject subject, final java.security.PrivilegedAction<T> action) { @@ -377,31 +377,32 @@ * passing it the provided {@code PrivilegedExceptionAction}, * as well as the newly constructed {@code AccessControlContext}. * - * <p> - * * @param subject the {@code Subject} that the specified * {@code action} will run as. This parameter - * may be {@code null}. <p> + * may be {@code null}. * * @param <T> the type of the value returned by the * PrivilegedExceptionAction's {@code run} method. * * @param action the code to be run as the specified - * {@code Subject}. <p> + * {@code Subject}. * * @return the value returned by the * PrivilegedExceptionAction's {@code run} method. * - * @exception PrivilegedActionException if the + * @throws PrivilegedActionException if the * {@code PrivilegedExceptionAction.run} - * method throws a checked exception. <p> + * method throws a checked exception. * - * @exception NullPointerException if the specified + * @throws NullPointerException if the specified * {@code PrivilegedExceptionAction} is - * {@code null}. <p> + * {@code null}. * - * @exception SecurityException if the caller does not have permission - * to invoke this method. + * @throws SecurityException if a security manager is installed and the + * caller does not have an + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("doAs")} permission to invoke this + * method. */ public static <T> T doAs(final Subject subject, final java.security.PrivilegedExceptionAction<T> action) @@ -435,29 +436,30 @@ * this method instantiates a new {@code AccessControlContext} * with an empty collection of ProtectionDomains. * - * <p> - * * @param subject the {@code Subject} that the specified * {@code action} will run as. This parameter - * may be {@code null}. <p> + * may be {@code null}. * * @param <T> the type of the value returned by the PrivilegedAction's * {@code run} method. * * @param action the code to be run as the specified - * {@code Subject}. <p> + * {@code Subject}. * * @param acc the {@code AccessControlContext} to be tied to the - * specified <i>subject</i> and <i>action</i>. <p> + * specified <i>subject</i> and <i>action</i>. * * @return the value returned by the PrivilegedAction's * {@code run} method. * - * @exception NullPointerException if the {@code PrivilegedAction} - * is {@code null}. <p> + * @throws NullPointerException if the {@code PrivilegedAction} + * is {@code null}. * - * @exception SecurityException if the caller does not have permission - * to invoke this method. + * @throws SecurityException if a security manager is installed and the + * caller does not have a + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("doAsPrivileged")} permission to invoke + * this method. */ public static <T> T doAsPrivileged(final Subject subject, final java.security.PrivilegedAction<T> action, @@ -495,34 +497,35 @@ * this method instantiates a new {@code AccessControlContext} * with an empty collection of ProtectionDomains. * - * <p> - * * @param subject the {@code Subject} that the specified * {@code action} will run as. This parameter - * may be {@code null}. <p> + * may be {@code null}. * * @param <T> the type of the value returned by the * PrivilegedExceptionAction's {@code run} method. * * @param action the code to be run as the specified - * {@code Subject}. <p> + * {@code Subject}. * * @param acc the {@code AccessControlContext} to be tied to the - * specified <i>subject</i> and <i>action</i>. <p> + * specified <i>subject</i> and <i>action</i>. * * @return the value returned by the * PrivilegedExceptionAction's {@code run} method. * - * @exception PrivilegedActionException if the + * @throws PrivilegedActionException if the * {@code PrivilegedExceptionAction.run} - * method throws a checked exception. <p> + * method throws a checked exception. * - * @exception NullPointerException if the specified + * @throws NullPointerException if the specified * {@code PrivilegedExceptionAction} is - * {@code null}. <p> + * {@code null}. * - * @exception SecurityException if the caller does not have permission - * to invoke this method. + * @throws SecurityException if a security manager is installed and the + * caller does not have a + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("doAsPrivileged")} permission to invoke + * this method. */ public static <T> T doAsPrivileged(final Subject subject, final java.security.PrivilegedExceptionAction<T> action, @@ -577,9 +580,12 @@ * to the returned {@code Set} affects the internal * {@code Principal} {@code Set} as well. * - * <p> + * <p> If a security manager is installed, the caller must have a + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("modifyPrincipals")} permission to modify + * the returned set, or a {@code SecurityException} will be thrown. * - * @return The {@code Set} of Principals associated with this + * @return the {@code Set} of Principals associated with this * {@code Subject}. */ public Set<Principal> getPrincipals() { @@ -600,8 +606,6 @@ * Modifications to the returned {@code Set} * will not affect the internal {@code Principal} {@code Set}. * - * <p> - * * @param <T> the type of the class modeled by {@code c} * * @param c the returned {@code Set} of Principals will all be @@ -610,8 +614,8 @@ * @return a {@code Set} of Principals that are instances of the * specified {@code Class}. * - * @exception NullPointerException if the specified {@code Class} - * is {@code null}. + * @throws NullPointerException if the specified {@code Class} + * is {@code null}. */ public <T extends Principal> Set<T> getPrincipals(Class<T> c) { @@ -632,9 +636,12 @@ * to the returned {@code Set} affects the internal public * Credential {@code Set} as well. * - * <p> + * <p> If a security manager is installed, the caller must have a + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("modifyPublicCredentials")} permission to modify + * the returned set, or a {@code SecurityException} will be thrown. * - * @return A {@code Set} of public credentials held by this + * @return a {@code Set} of public credentials held by this * {@code Subject}. */ public Set<Object> getPublicCredentials() { @@ -653,20 +660,18 @@ * to the returned {@code Set} affects the internal private * Credential {@code Set} as well. * - * <p> A caller requires permissions to access the Credentials - * in the returned {@code Set}, or to modify the - * {@code Set} itself. A {@code SecurityException} - * is thrown if the caller does not have the proper permissions. + * <p> If a security manager is installed, the caller must have a + * {@link AuthPermission#AuthPermission(String) + * AuthPermission("modifyPrivateCredentials")} permission to modify + * the returned set, or a {@code SecurityException} will be thrown. * * <p> While iterating through the {@code Set}, - * a {@code SecurityException} is thrown - * if the caller does not have permission to access a - * particular Credential. The {@code Iterator} - * is nevertheless advanced to next element in the {@code Set}. + * a {@code SecurityException} is thrown if a security manager is installed + * and the caller does not have a {@link PrivateCredentialPermission} + * to access a particular Credential. The {@code Iterator} + * is nevertheless advanced to the next element in the {@code Set}. * - * <p> - * - * @return A {@code Set} of private credentials held by this + * @return a {@code Set} of private credentials held by this * {@code Subject}. */ public Set<Object> getPrivateCredentials() { @@ -695,8 +700,6 @@ * Modifications to the returned {@code Set} * will not affect the internal public Credential {@code Set}. * - * <p> - * * @param <T> the type of the class modeled by {@code c} * * @param c the returned {@code Set} of public credentials will all be @@ -705,7 +708,7 @@ * @return a {@code Set} of public credentials that are instances * of the specified {@code Class}. * - * @exception NullPointerException if the specified {@code Class} + * @throws NullPointerException if the specified {@code Class} * is {@code null}. */ public <T> Set<T> getPublicCredentials(Class<T> c) { @@ -723,9 +726,9 @@ * {@code Subject} that are instances or subclasses of the specified * {@code Class}. * - * <p> The caller must have permission to access all of the - * requested Credentials, or a {@code SecurityException} - * will be thrown. + * <p> If a security manager is installed, the caller must have a + * {@link PrivateCredentialPermission} to access all of the requested + * Credentials, or a {@code SecurityException} will be thrown. * * <p> The returned {@code Set} is not backed by this Subject's * internal private Credential {@code Set}. A new @@ -733,8 +736,6 @@ * Modifications to the returned {@code Set} * will not affect the internal private Credential {@code Set}. * - * <p> - * * @param <T> the type of the class modeled by {@code c} * * @param c the returned {@code Set} of private credentials will all be @@ -743,7 +744,7 @@ * @return a {@code Set} of private credentials that are instances * of the specified {@code Class}. * - * @exception NullPointerException if the specified {@code Class} + * @throws NullPointerException if the specified {@code Class} * is {@code null}. */ public <T> Set<T> getPrivateCredentials(Class<T> c) { @@ -772,19 +773,18 @@ * equal if their {@code Principal} and {@code Credential} * Sets are equal. * - * <p> - * * @param o Object to be compared for equality with this * {@code Subject}. * * @return true if the specified Object is equal to this * {@code Subject}. * - * @exception SecurityException if the caller does not have permission - * to access the private credentials for this {@code Subject}, - * or if the caller does not have permission to access the - * private credentials for the provided {@code Subject}. + * @throws SecurityException if a security manager is installed and the + * caller does not have a {@link PrivateCredentialPermission} + * permission to access the private credentials for this + * {@code Subject} or the provided {@code Subject}. */ + @Override public boolean equals(Object o) { if (o == null) { @@ -834,10 +834,9 @@ /** * Return the String representation of this {@code Subject}. * - * <p> - * * @return the String representation of this {@code Subject}. */ + @Override public String toString() { return toString(true); } @@ -895,13 +894,13 @@ /** * Returns a hashcode for this {@code Subject}. * - * <p> - * * @return a hashcode for this {@code Subject}. * - * @exception SecurityException if the caller does not have permission - * to access this Subject's private credentials. + * @throws SecurityException if a security manager is installed and the + * caller does not have a {@link PrivateCredentialPermission} + * permission to access this Subject's private credentials. */ + @Override public int hashCode() { /** @@ -996,7 +995,7 @@ * * @param coll A {@code Collection} to be tested for null references * - * @exception NullPointerException if the specified collection is either + * @throws NullPointerException if the specified collection is either * {@code null} or contains a {@code null} element */ private static void collectionNullClean(Collection<?> coll) { @@ -1546,7 +1545,7 @@ } } - static class AuthPermissionHolder { + static final class AuthPermissionHolder { static final AuthPermission DO_AS_PERMISSION = new AuthPermission("doAs");