# HG changeset patch # User mullan # Date 1408365908 14400 # Node ID 6a57ce3f21f143cd7b776e4ca1d0916e6268a576 # Parent 76e62811f63b50fef6b7719178a316fccddb49ee 7026255: Methods of Subject that throw SecurityException do not specify what permissions are required Reviewed-by: xuelei diff -r 76e62811f63b -r 6a57ce3f21f1 jdk/src/share/classes/javax/security/auth/Subject.java --- 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")}. - *

* * @param readOnly true if the {@code Subject} is to be read-only, - * and false otherwise.

+ * and false otherwise. * * @param principals the {@code Set} of Principals - * to be associated with this {@code Subject}.

+ * to be associated with this {@code Subject}. * * @param pubCredentials the {@code Set} of public credentials - * to be associated with this {@code Subject}.

+ * 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. * - *

- * - * @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. * - *

- * * @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. * - *

- * * @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}.

+ * @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}. * - *

- * * @param subject the {@code Subject} that the specified * {@code action} will run as. This parameter - * may be {@code null}.

+ * may be {@code null}. * * @param 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}.

+ * {@code Subject}. * * @return the value returned by the PrivilegedAction's * {@code run} method. * - * @exception NullPointerException if the {@code PrivilegedAction} - * is {@code null}.

+ * @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 doAs(final Subject subject, final java.security.PrivilegedAction action) { @@ -377,31 +377,32 @@ * passing it the provided {@code PrivilegedExceptionAction}, * as well as the newly constructed {@code AccessControlContext}. * - *

- * * @param subject the {@code Subject} that the specified * {@code action} will run as. This parameter - * may be {@code null}.

+ * may be {@code null}. * * @param 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}.

+ * {@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.

+ * method throws a checked exception. * - * @exception NullPointerException if the specified + * @throws NullPointerException if the specified * {@code PrivilegedExceptionAction} is - * {@code null}.

+ * {@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 doAs(final Subject subject, final java.security.PrivilegedExceptionAction action) @@ -435,29 +436,30 @@ * this method instantiates a new {@code AccessControlContext} * with an empty collection of ProtectionDomains. * - *

- * * @param subject the {@code Subject} that the specified * {@code action} will run as. This parameter - * may be {@code null}.

+ * may be {@code null}. * * @param 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}.

+ * {@code Subject}. * * @param acc the {@code AccessControlContext} to be tied to the - * specified subject and action.

+ * specified subject and action. * * @return the value returned by the PrivilegedAction's * {@code run} method. * - * @exception NullPointerException if the {@code PrivilegedAction} - * is {@code null}.

+ * @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 doAsPrivileged(final Subject subject, final java.security.PrivilegedAction action, @@ -495,34 +497,35 @@ * this method instantiates a new {@code AccessControlContext} * with an empty collection of ProtectionDomains. * - *

- * * @param subject the {@code Subject} that the specified * {@code action} will run as. This parameter - * may be {@code null}.

+ * may be {@code null}. * * @param 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}.

+ * {@code Subject}. * * @param acc the {@code AccessControlContext} to be tied to the - * specified subject and action.

+ * specified subject and action. * * @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.

+ * method throws a checked exception. * - * @exception NullPointerException if the specified + * @throws NullPointerException if the specified * {@code PrivilegedExceptionAction} is - * {@code null}.

+ * {@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 doAsPrivileged(final Subject subject, final java.security.PrivilegedExceptionAction action, @@ -577,9 +580,12 @@ * to the returned {@code Set} affects the internal * {@code Principal} {@code Set} as well. * - *

+ *

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 getPrincipals() { @@ -600,8 +606,6 @@ * Modifications to the returned {@code Set} * will not affect the internal {@code Principal} {@code Set}. * - *

- * * @param 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 Set getPrincipals(Class c) { @@ -632,9 +636,12 @@ * to the returned {@code Set} affects the internal public * Credential {@code Set} as well. * - *

+ *

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 getPublicCredentials() { @@ -653,20 +660,18 @@ * to the returned {@code Set} affects the internal private * Credential {@code Set} as well. * - *

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. + *

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. * *

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}. * - *

- * - * @return A {@code Set} of private credentials held by this + * @return a {@code Set} of private credentials held by this * {@code Subject}. */ public Set getPrivateCredentials() { @@ -695,8 +700,6 @@ * Modifications to the returned {@code Set} * will not affect the internal public Credential {@code Set}. * - *

- * * @param 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 Set getPublicCredentials(Class c) { @@ -723,9 +726,9 @@ * {@code Subject} that are instances or subclasses of the specified * {@code Class}. * - *

The caller must have permission to access all of the - * requested Credentials, or a {@code SecurityException} - * will be thrown. + *

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. * *

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}. * - *

- * * @param 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 Set getPrivateCredentials(Class c) { @@ -772,19 +773,18 @@ * equal if their {@code Principal} and {@code Credential} * Sets are equal. * - *

- * * @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}. * - *

- * * @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}. * - *

- * * @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");