Index: modules/security/src/main/java/common/java/security/GuardedObject.java =================================================================== --- modules/security/src/main/java/common/java/security/GuardedObject.java (revision 395586) +++ modules/security/src/main/java/common/java/security/GuardedObject.java (working copy) @@ -25,7 +25,8 @@ import java.io.Serializable; /** - * @com.intel.drl.spec_ref + * GuardedObject controls access to an object, by checking all requests for the + * object with a Guard. * */ public class GuardedObject implements Serializable { @@ -45,17 +46,31 @@ */ private final Guard guard; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a GuardedObject to protect access to the specified Object + * using the specified Guard. + * + * @param object + * the Object to guard + * @param guard + * the Guard + */ public GuardedObject(Object object, Guard guard) { this.object = object; this.guard = guard; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Checks whether access should be granted to the object. If access is + * granted, this method returns the object. If it is not granted, then a + * SecurityException is thrown. + * + * + * @return the guarded object + * + * @exception java.lang.SecurityException + * If access is not granted to the object + */ public Object getObject() throws SecurityException { if (guard != null) { guard.checkGuard(object); Index: modules/security/src/main/java/common/java/security/SecureClassLoader.java =================================================================== --- modules/security/src/main/java/common/java/security/SecureClassLoader.java (revision 395586) +++ modules/security/src/main/java/common/java/security/SecureClassLoader.java (working copy) @@ -25,7 +25,11 @@ import java.util.HashMap; /** - * @com.intel.drl.spec_ref + * SecureClassLoaders are used to dynamically load, link and install classes + * into a running image. Additionally, they (optionally) associate the classes + * they create with a code source and provide mechanisms to allow the relevant + * permissions to be retrieved. + * */ public class SecureClassLoader extends ClassLoader { Index: modules/security/src/main/java/common/java/security/KeyStore.java =================================================================== --- modules/security/src/main/java/common/java/security/KeyStore.java (revision 395586) +++ modules/security/src/main/java/common/java/security/KeyStore.java (working copy) @@ -1056,4 +1056,4 @@ .toString()); } } -} \ No newline at end of file +} Index: modules/security/src/main/java/common/java/security/PrivilegedActionException.java =================================================================== --- modules/security/src/main/java/common/java/security/PrivilegedActionException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/PrivilegedActionException.java (working copy) @@ -21,8 +21,11 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Instances of this class are used to wrap exceptions which occur within + * privileged operations. + * */ public class PrivilegedActionException extends Exception { @@ -36,32 +39,41 @@ */ private Exception exception; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its exception filled in. + * @param ex + */ public PrivilegedActionException(Exception ex) { super(ex); this.exception = ex; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the exception which caused the receiver to be thrown. + * @return exception + */ public Exception getException() { return exception; // return ( getCause() instanceof Exception ) ? // getCause() : null; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the cause of this Throwable, or null if there is no cause. + * + * + * @return Throwable The receiver's cause. + */ public Throwable getCause() { return exception; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return String a printable representation for the receiver. + */ public String toString() { String s = getClass().getName(); return exception == null ? s : s + ": " + exception; Index: modules/security/src/main/java/common/java/security/DigestInputStream.java =================================================================== --- modules/security/src/main/java/common/java/security/DigestInputStream.java (revision 395586) +++ modules/security/src/main/java/common/java/security/DigestInputStream.java (working copy) @@ -47,23 +47,44 @@ this.digest = digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the MessageDigest which the receiver uses when computing the + * hash. + * + * + * @return MessageDigest the digest the receiver uses when computing the + * hash. + * + */ public MessageDigest getMessageDigest() { return digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Sets the MessageDigest which the receiver will use when computing the + * hash. + * + * + * @param digest + * MessageDigest the digest to use when computing the hash. + * + * @see MessageDigest + * @see #on + */ public void setMessageDigest(MessageDigest digest) { this.digest = digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Reads the next byte and answers it as an int. Updates the digest for the + * byte if this fuction is enabled. + * + * + * @return int the byte which was read or -1 at end of stream. + * + * @exception java.io.IOException + * If reading the source stream causes an IOException. + */ public int read() throws IOException { // read the next byte int byteRead = in.read(); @@ -93,16 +114,27 @@ return bytesRead; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Enables or disables the digest function (default is on). + * + * + * @param on + * boolean true if the digest should be computed, and false + * otherwise. + * + * @see MessageDigest + */ public void on(boolean on) { isOn = on; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return String a printable representation for the receiver. + */ public String toString() { return super.toString() + ", " + digest.toString() + (isOn ? ", is on" : ", is off"); Index: modules/security/src/main/java/common/java/security/DigestOutputStream.java =================================================================== --- modules/security/src/main/java/common/java/security/DigestOutputStream.java (revision 395586) +++ modules/security/src/main/java/common/java/security/DigestOutputStream.java (working copy) @@ -47,16 +47,30 @@ this.digest = digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the MessageDigest which the receiver uses when computing the + * hash. + * + * + * @return MessageDigest the digest the receiver uses when computing the + * hash. + */ + public MessageDigest getMessageDigest() { return digest; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Sets the MessageDigest which the receiver will use when computing the + * hash. + * + * + * @param digest + * MessageDigest the digest to use when computing the hash. + * + * @see MessageDigest + * @see #on + */ public void setMessageDigest(MessageDigest digest) { this.digest = digest; } @@ -85,16 +99,27 @@ out.write(b, off, len); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Enables or disables the digest function (default is on). + * + * + * @param on + * boolean true if the digest should be computed, and false + * otherwise. + * + * @see MessageDigest + */ public void on(boolean on) { isOn = on; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return String a printable representation for the receiver. + */ public String toString() { return super.toString() + ", " + digest.toString() + (isOn ? ", is on" : ", is off"); Index: modules/security/src/main/java/common/java/security/InvalidAlgorithmParameterException.java =================================================================== --- modules/security/src/main/java/common/java/security/InvalidAlgorithmParameterException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/InvalidAlgorithmParameterException.java (working copy) @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents invalid algorithm parameters to cryprographic services. * */ public class InvalidAlgorithmParameterException extends @@ -32,16 +33,22 @@ */ private static final long serialVersionUID = 2864672297499471472L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public InvalidAlgorithmParameterException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public InvalidAlgorithmParameterException() { } Index: modules/security/src/main/java/common/java/security/InvalidKeyException.java =================================================================== --- modules/security/src/main/java/common/java/security/InvalidKeyException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/InvalidKeyException.java (working copy) @@ -21,9 +21,12 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Used when invalid cryptography keys are used. * + * @see Throwable + * @see Error */ public class InvalidKeyException extends KeyException { @@ -32,16 +35,22 @@ */ private static final long serialVersionUID = 5698479920593359816L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public InvalidKeyException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public InvalidKeyException() { } Index: modules/security/src/main/java/common/java/security/Provider.java =================================================================== --- modules/security/src/main/java/common/java/security/Provider.java (revision 395586) +++ modules/security/src/main/java/common/java/security/Provider.java (working copy) @@ -119,34 +119,46 @@ putProviderInfo(); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the name of this provider. + * + * + * + * @return String name of the provider + */ public String getName() { return name; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the version number for the services being provided + * + * + * + * @return double version number for the services being provided + */ public double getVersion() { return version; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the generic information about the services being provided. + * + * + * + * @return String generic description of the services being provided + */ public String getInfo() { return info; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return a printable representation for the receiver. + */ public String toString() { return name + " provider, Ver. " + version + " " + info; } @@ -980,10 +992,13 @@ return true; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers a string containing a concise, human-readable + * description of the receiver. + * + * + * @return a printable representation for the receiver. + */ public String toString() { String result = "Provider " + provider.getName() + " Service " + type + "." + algorithm + " " + className; @@ -996,4 +1011,4 @@ return result; } } -} \ No newline at end of file +} Index: modules/security/src/main/java/common/java/security/BasicPermission.java =================================================================== --- modules/security/src/main/java/common/java/security/BasicPermission.java (revision 395586) +++ modules/security/src/main/java/common/java/security/BasicPermission.java (working copy) @@ -35,24 +35,35 @@ import java.util.Map; /** - * @com.intel.drl.spec_ref + * Superclass of permissions which have names but no action lists. + * */ + public abstract class BasicPermission extends Permission implements Serializable { private static final long serialVersionUID = 6279438298436773498L; - /** - * @com.intel.drl.spec_ref. - */ + /** + * Creates an instance of this class with the given name and action list. + * + * @param name + * String the name of the new permission. + */ public BasicPermission(String name) { super(name); checkName(name); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Creates an instance of this class with the given name and action list. + * The action list is ignored. + * + * @param name + * String the name of the new permission. + * @param action + * String ignored. + */ public BasicPermission(String name, String action) { super(name); checkName(name); @@ -70,9 +81,17 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. In this + * case, the receiver and the object must have the same class and name. + * + * @param obj + * the object to compare with this object + * @return true if the object is the same as this object + * false if it is different from this object + * @see #hashCode + */ public boolean equals(Object obj) { if (obj == this) { return true; @@ -84,23 +103,37 @@ return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to equals must + * answer the same value for this method. + * + * @return int the receiver's hash + * + * @see #equals + */ public int hashCode() { return getName().hashCode(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the actions associated with the receiver. BasicPermission objects + * have no actions, so answer the empty string. + * + * @return String the actions associated with the receiver. + */ public String getActions() { return ""; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { if (permission != null && permission.getClass() == this.getClass()) { return nameImplies(getName(), permission.getName()); @@ -137,9 +170,21 @@ return true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new PermissionCollection for holding permissions of this class. + * Answer null if any permission collection can be used. + *

+ * Note: For BasicPermission (and subclasses which do not override this + * method), the collection which is returned does not invoke the + * .implies method of the permissions which are stored in it when checking + * if the collection implies a permission. Instead, it assumes that if the + * type of the permission is correct, and the name of the permission is + * correct, there is a match. + * + * @return a new PermissionCollection or null + * + * @see java.security.BasicPermissionCollection + */ public PermissionCollection newPermissionCollection() { return new BasicPermissionCollection(); } @@ -229,12 +274,14 @@ return Collections.enumeration(items.values()); } - /** - * Checks if the particular permission is implied by this collection. - * - * @see java.security.BasicPermission - * @see java.security.PermissionCollection#implies(java.security.Permission) - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { if (permission == null || permission.getClass() != permClass) { return false; Index: modules/security/src/main/java/common/java/security/Policy.java =================================================================== --- modules/security/src/main/java/common/java/security/Policy.java (revision 395586) +++ modules/security/src/main/java/common/java/security/Policy.java (working copy) @@ -28,9 +28,9 @@ /** - * @com.intel.drl.spec_ref + * Abstract superclass of classes which represent the system security policy. + * */ - public abstract class Policy { // Key to security properties, defining default policy provider. @@ -47,20 +47,40 @@ // The policy currently in effect. private static Policy activePolicy; - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a PermissionCollection describing what permissions are available + * to the given CodeSource based on the current security policy. + *

+ * Note that this method is not called for classes which are in + * the system domain (i.e. system classes). System classes are + * always given full permissions (i.e. AllPermission). This can + * not be changed by installing a new Policy. + * + * + * @param cs + * CodeSource the code source to compute the permissions for. + * @return PermissionCollection the permissions the code source should have. + */ public abstract PermissionCollection getPermissions(CodeSource cs); - /** - * @com.intel.drl.spec_ref - */ + /** + * Reloads the policy configuration, depending on how the type of source + * location for the policy information. + * + * + */ public abstract void refresh(); - /** - * @com.intel.drl.spec_ref - * The returned collection does not include static permissions of the domain. - */ + /** + * Answers a PermissionCollection describing what permissions are available + * to the given ProtectionDomain (more specifically, its CodeSource) based + * on the current security policy. + * + * @param domain + * ProtectionDomain the protection domain to compute the + * permissions for. + * @return PermissionCollection the permissions the code source should have. + */ public PermissionCollection getPermissions(ProtectionDomain domain) { if (domain != null) { return getPermissions(domain.getCodeSource()); @@ -68,9 +88,16 @@ return new Permissions(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers whether the Permission is implied by the PermissionCollection of + * the Protection Domain + * + * @param domain + * ProtectionDomain for which Permission to be checked + * @param permission + * Permission for which authorization is to be verified + * @return boolean Permission implied by ProtectionDomain + */ public boolean implies(ProtectionDomain domain, Permission permission) { if (domain != null) { PermissionCollection total = getPermissions(domain); @@ -89,11 +116,13 @@ return false; } - /** - * @com.intel.drl.spec_ref - * If policy was set to null, loads default provider, - * so this method never returns null. - */ + /** + * Answers the current system security policy. If no policy has been + * instantiated then this is done using the security property policy.provider + * + * + * @return Policy the current system security policy. + */ public static Policy getPolicy() { SecurityManager sm = System.getSecurityManager(); if (sm != null) { @@ -166,11 +195,13 @@ return current; } - /** - * @com.intel.drl.spec_ref - * Policy assigment is synchronized with default provider loading, to avoid - * non-deterministic behavior. - */ + /** + * Sets the system-wide policy object if it is permitted by the security + * manager. + * + * @param policy + * Policy the policy object that needs to be set. + */ public static void setPolicy(Policy policy) { SecurityManager sm = System.getSecurityManager(); if (sm != null) { Index: modules/security/src/main/java/common/java/security/UnresolvedPermission.java =================================================================== --- modules/security/src/main/java/common/java/security/UnresolvedPermission.java (revision 395586) +++ modules/security/src/main/java/common/java/security/UnresolvedPermission.java (working copy) @@ -38,14 +38,13 @@ import org.apache.harmony.security.fortress.PolicyUtils; - /** - * @com.intel.drl.spec_ref - * Technically, the resolution of UnresolvedPermissions - * and substitution by actual permissions takes place in - * implies() method of a - * Permissions collection, right before - * actual checking. + * Holds permissions which are of an unknown type when a policy file is read. + * + * Technically, the resolution of UnresolvedPermissions and + * substitution by actual permissions takes place in the + * implies() method of a Permissions + * collection, right before actual checking. * */ public final class UnresolvedPermission extends Permission @@ -73,9 +72,17 @@ // Cached hash value private transient int hash; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its type, name, and + * certificates set to the arguments by definition, actions are ignored + * + * @param type + * class of permission object + * @param name + * identifies the permission that could not be resolved + * @param actions + * @param certs + */ public UnresolvedPermission(String type, String name, String actions, Certificate[] certs) { super(type); @@ -108,9 +115,19 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. In this + * case, the receiver and the object must have the same class, permission + * name, actions, and certificates + * + * @param obj + * the object to compare with this object + * @return true if the object is the same as this object, + * false otherwise. + * + * @see #hashCode + */ public boolean equals(Object obj) { if (obj == this) { return true; @@ -130,9 +147,15 @@ return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to equals must + * answer the same value for this method. + * + * @return the receiver's hash + * + * @see #equals + */ public int hashCode() { if (hash == 0) { hash = getName().hashCode(); @@ -146,9 +169,12 @@ return hash; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the actions associated with the receiver. Since + * UnresolvedPermission objects have no actions, answer the empty string. + * + * @return the actions associated with the receiver. + */ public String getActions() { return ""; } @@ -186,30 +212,43 @@ return null; } - /** - * @com.intel.drl.spec_ref - * The enclosed target permission would be resolved - * and consulted for implication if this - * UnresolvedPermission is an element of a - * Permissions collection and the - * collection's implies() method is - * called. - */ + /** + * Indicates whether the argument permission is implied by the + * receiver. UnresolvedPermission objects imply nothing + * because nothing is known about them yet. + * + * Before actual implication checking, this method tries to + * resolve UnresolvedPermissions (if any) against the passed + * instance. Successfully resolved permissions (if any) are + * taken into account during further processing. + * + * @param permission + * the permission to check + * @return always replies false + */ public boolean implies(Permission permission) { return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return a printable representation for the receiver. + */ public String toString() { return "(unresolved " + getName() + " " + targetName + " " + targetActions + ")"; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new PermissionCollection for holding permissions of this class. + * Answer null if any permission collection can be used. + * + * @return a new PermissionCollection or null + * + * @see java.security.BasicPermissionCollection + */ public PermissionCollection newPermissionCollection() { return new UnresolvedPermissionCollection(); } Index: modules/security/src/main/java/common/java/security/PermissionCollection.java =================================================================== --- modules/security/src/main/java/common/java/security/PermissionCollection.java (revision 395586) +++ modules/security/src/main/java/common/java/security/PermissionCollection.java (working copy) @@ -27,7 +27,8 @@ import java.util.List; /** - * @com.intel.drl.spec_ref + * Abstract superclass of classes which are collections of Permission objects. + * */ public abstract class PermissionCollection implements Serializable { @@ -42,36 +43,65 @@ private boolean readOnly; // = false; /** - * @com.intel.drl.spec_ref + * Adds the argument to the collection. + * + * + * @param permission + * java.security.Permission the permission to add to the + * collection. + * @exception IllegalStateException + * if the collection is read only. */ public abstract void add(Permission permission); /** - * @com.intel.drl.spec_ref + * Answers an enumeration of the permissions in the receiver. + * + * + * @return Enumeration the permissions in the receiver. */ public abstract Enumeration elements(); /** - * @com.intel.drl.spec_ref + * Indicates whether the argument permission is implied by the permissions + * contained in the receiver. + * + * + * @return boolean true if the argument permission is implied + * by the permissions in the receiver, and false if + * it is not. + * @param permission + * java.security.Permission the permission to check */ public abstract boolean implies(Permission permission); /** - * @com.intel.drl.spec_ref + * Indicates whether new permissions can be added to the receiver. + * + * + * @return boolean true if the receiver is read only + * false if new elements can still be added to the + * receiver. */ public boolean isReadOnly() { return readOnly; } /** - * @com.intel.drl.spec_ref + * Marks the receiver as read only, so that no new permissions can be added + * to it. + * */ public void setReadOnly() { readOnly = true; } /** - * @com.intel.drl.spec_ref + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return a printable representation for the receiver. */ public String toString() { List elist = new ArrayList(100); @@ -95,4 +125,4 @@ } return result.append("\n)").toString(); } -} \ No newline at end of file +} Index: modules/security/src/main/java/common/java/security/Security.java =================================================================== --- modules/security/src/main/java/common/java/security/Security.java (revision 395586) +++ modules/security/src/main/java/common/java/security/Security.java (working copy) @@ -42,12 +42,9 @@ import org.apache.harmony.security.fortress.SecurityAccess; import org.apache.harmony.security.fortress.Services; - /** - * @com.intel.drl.spec_ref - * + * For access to security providers and properties. */ - public final class Security { // Security properties @@ -133,11 +130,13 @@ // + "No providers registered."); } - /** - * @com.intel.drl.spec_ref - * - * @deprecated Use {@link KeyFactory} and {@link AlgorithmParameters} to get - * algorithm property information. + /** + * Deprecated method which returns null. + * @param algName + * @param propName + * @return null + * + * @deprecated Use AlgorithmParameters and KeyFactory instead */ public static String getAlgorithmProperty(String algName, String propName) { if (algName == null || propName == null) { @@ -179,10 +178,15 @@ return result; } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Adds the extra provider to the collection of providers. + * @param provider + * + * @return int The priority/position of the provider added. + * @exception SecurityException + * If there is a SecurityManager installed and it denies + * adding a new provider. + */ public static int addProvider(Provider provider) { return insertProviderAt(provider, 0); } @@ -231,10 +235,19 @@ return Services.getProvider(name); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Returns the collection of providers which meet the user supplied string + * filter. + * + * @param filter + * case-insensitive filter + * @return the providers which meet the user supplied string filter + * filter. A null value signifies + * that none of the installed providers meets the filter + * specification + * @exception InvalidParameterException + * if an unusable filter is supplied + */ public static Provider[] getProviders(String filter) { if (filter == null) { throw new NullPointerException("The filter is null"); @@ -317,10 +330,19 @@ } } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Answers the value of the security property named by the argument. + * + * + * @param key + * String The property name + * @return String The property value + * + * @exception SecurityException + * If there is a SecurityManager installed and it will not + * allow the property to be fetched from the current access + * control context. + */ public static String getProperty(String key) { if (key == null) { throw new NullPointerException("The key is null"); @@ -332,10 +354,19 @@ return secprops.getProperty(key); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Sets a given security property. + * + * + * @param key + * String The property name. + * @param datnum + * String The property value. + * @exception SecurityException + * If there is a SecurityManager installed and it will not + * allow the property to be set from the current access + * control context. + */ public static void setProperty(String key, String datnum) { SecurityManager sm = System.getSecurityManager(); if (sm != null) { Index: modules/security/src/main/java/common/java/security/Permissions.java =================================================================== --- modules/security/src/main/java/common/java/security/Permissions.java (revision 395586) +++ modules/security/src/main/java/common/java/security/Permissions.java (working copy) @@ -35,7 +35,8 @@ import java.util.NoSuchElementException; /** - * @com.intel.drl.spec_ref + * A heterogeneous collection of permissions. + * */ public final class Permissions extends PermissionCollection implements Serializable { @@ -57,9 +58,14 @@ */ private boolean allEnabled; // = false; - /** - * @com.intel.drl.spec_ref - */ + /** + * Adds the argument to the collection. + * + * + * @param permission + * java.security.Permission the permission to add to the + * collection + */ public void add(Permission permission) { if (isReadOnly()) { throw new SecurityException("collection is read-only"); @@ -94,7 +100,10 @@ } /** - * @com.intel.drl.spec_ref + * Answers an enumeration of the permissions in the receiver. + * + * + * @return Enumeration the permissions in the receiver. */ public Enumeration elements() { return new MetaEnumeration(klasses.values().iterator()); @@ -157,14 +166,17 @@ } } - /** - * @com.intel.drl.spec_ref - * Before actual implication checking, this method - * tries to resolve UnresolvedPermissions (if any) - * against the passed instance. Successfully - * resolved permissions (if any) are taken into - * account during further processing. - */ + /** + * Indicates whether the argument permission is implied by the permissions + * contained in the receiver. + * + * + * @return boolean true if the argument permission is implied + * by the permissions in the receiver, and false if + * it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { if (allEnabled) { return true; @@ -266,27 +278,39 @@ */ private final Hashtable perms = new Hashtable(); - /** - * Adds passed permission (of any type) to the collection. The read-only - * flag is ignored, as this class is used as internal storage only. - */ + /** + * Adds the argument to the collection. + * + * + * @param permission + * java.security.Permission the permission to add to the + * collection + */ public void add(Permission permission) { perms.put(permission, permission); } - /** - * Returns enumeration of contained elements. - */ + /** + * Answers an enumeration of the permissions in the receiver. + * + * + * @return Enumeration the permissions in the receiver. + */ public Enumeration elements() { return perms.elements(); } - /** - * Checks if this collection implies the particular permission. - * - * @return true if some of contained permissions implies the passed - * permission, false otherwise - */ + /** + * Indicates whether the argument permission is implied by the permissions + * contained in the receiver. + * + * + * @return boolean true if the argument permission is implied + * by the permissions in the receiver, and false if + * it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { for (Enumeration elements = elements(); elements.hasMoreElements();) { if (((Permission)elements.nextElement()).implies(permission)) { @@ -295,4 +319,4 @@ } return false; } -} \ No newline at end of file +} Index: modules/security/src/main/java/common/java/security/SignatureException.java =================================================================== --- modules/security/src/main/java/common/java/security/SignatureException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/SignatureException.java (working copy) @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents generic security exceptions. * */ public class SignatureException extends GeneralSecurityException { @@ -31,16 +32,22 @@ */ private static final long serialVersionUID = 7509989324975124438L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public SignatureException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public SignatureException() { } Index: modules/security/src/main/java/common/java/security/AccessControlException.java =================================================================== --- modules/security/src/main/java/common/java/security/AccessControlException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/AccessControlException.java (working copy) @@ -21,10 +21,12 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This runtime exception is thrown when an access control check indicates that + * access should not be granted. + * */ - public class AccessControlException extends SecurityException { private static final long serialVersionUID = 5138225684096988535L; @@ -34,24 +36,39 @@ */ private Permission perm; // Named as demanded by Serialized Form. - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param message + * String The detail message for the exception. + */ public AccessControlException(String message) { super(message); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback, message and + * associated permission all filled in. + * + * + * @param message + * String The detail message for the exception. + * @param perm + * Permission The failed permission. + */ public AccessControlException(String message, Permission perm) { super(message); this.perm = perm; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the receiver's permission. + * + * + * @return Permission the receiver's permission + */ public Permission getPermission() { return perm; } Index: modules/security/src/main/java/common/java/security/Principal.java =================================================================== --- modules/security/src/main/java/common/java/security/Principal.java (revision 395586) +++ modules/security/src/main/java/common/java/security/Principal.java (working copy) @@ -21,10 +21,12 @@ package java.security; -/** - * @com.intel.drl.spec_ref + +/** + * Principals are objects which have identities. These can be individuals, + * groups, corporations, unique program executions, etc. + * */ - public interface Principal { /** * @com.intel.drl.spec_ref Index: modules/security/src/main/java/common/java/security/DomainCombiner.java =================================================================== --- modules/security/src/main/java/common/java/security/DomainCombiner.java (revision 395586) +++ modules/security/src/main/java/common/java/security/DomainCombiner.java (working copy) @@ -21,8 +21,11 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * A DomainCombiner is a way to update the protection domains from an + * AccessControlContext + * */ public interface DomainCombiner { /** Index: modules/security/src/main/java/common/java/security/Permission.java =================================================================== --- modules/security/src/main/java/common/java/security/Permission.java (revision 395586) +++ modules/security/src/main/java/common/java/security/Permission.java (working copy) @@ -23,8 +23,10 @@ import java.io.Serializable; + /** - * @com.intel.drl.spec_ref + * Abstract superclass of all classes which represent permission to access + * system resources. * */ public abstract class Permission implements Guard, Serializable { @@ -41,31 +43,57 @@ */ public abstract boolean equals(Object obj); - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to .equals must + * answer the same value for this method. + * + * + * @return int the receiver's hash. + * + * @see #equals + */ public abstract int hashCode(); - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the actions associated with the receiver. Subclasses should + * return their actions in canonical form. If no actions are associated with + * the receiver, the empty string should be returned. + * + * + * @return String the receiver's actions. + */ public abstract String getActions(); - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * Permission the permission to check. + */ public abstract boolean implies(Permission permission); - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its name set to the + * argument. + * + * + * @param name + * String the name of the permission. + */ public Permission(String name) { this.name = name; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the name of the receiver. + * + * + * @return String the receiver's name. + */ public final String getName() { return name; } @@ -80,16 +108,25 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new PermissionCollection for holding permissions of this class. + * Answer null if any permission collection can be used. + * + * + * @return PermissionCollection or null a suitable permission collection for + * instances of the class of the receiver. + */ public PermissionCollection newPermissionCollection() { return null; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return String a printable representation for the receiver. + */ public String toString() { String actions = getActions(); actions = (actions == null || actions.length() == 0) ? "" : " " Index: modules/security/src/main/java/common/java/security/Key.java =================================================================== --- modules/security/src/main/java/common/java/security/Key.java (revision 395586) +++ modules/security/src/main/java/common/java/security/Key.java (working copy) @@ -24,8 +24,9 @@ import java.io.Serializable; /** - * @com.intel.drl.spec_ref + * Defines the basic properties of all key objects. * + * @see PublicKey */ public interface Key extends Serializable { /** @@ -34,17 +35,25 @@ public static final long serialVersionUID = 6603384152749567654L; /** - * @com.intel.drl.spec_ref + * Answers the name of the algorithm that this key will work + * with. If the algorithm is unknown, it answers null. + * + * @return String the receiver's algorithm */ public String getAlgorithm(); /** - * @com.intel.drl.spec_ref + * Answers the name of the format used to encode the key, or null + * if it can not be encoded. + * + * @return String the receiver's encoding format */ public String getFormat(); /** - * @com.intel.drl.spec_ref + * Answers the encoded form of the receiver. + * + * @return byte[] the encoded form of the receiver */ public byte[] getEncoded(); -} \ No newline at end of file +} Index: modules/security/src/main/java/common/java/security/CodeSource.java =================================================================== --- modules/security/src/main/java/common/java/security/CodeSource.java (revision 395586) +++ modules/security/src/main/java/common/java/security/CodeSource.java (working copy) @@ -70,9 +70,15 @@ // Cached factory used to build CertPath-s in getCodeSigners(). private transient CertificateFactory factory; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its url and certificates + * fields filled in from the arguments. + * + * @param location + * URL the URL. + * @param certs + * Certificate[] the Certificates. + */ public CodeSource(URL location, Certificate[] certs) { this.location = location; if (certs != null) { @@ -92,9 +98,19 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. In this + * case, the receiver and the object must have the same URL and the same + * collection of certificates. + * + * + * @param obj + * the object to compare with this object + * @return true if the object is the same as this object + * false if it is different from this object + * @see #hashCode + */ public boolean equals(Object obj) { if (obj == this) { return true; @@ -130,9 +146,12 @@ return true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the certificates held onto by the receiver. + * + * + * @return Certificate[] the receiver's certificates + */ public final Certificate[] getCertificates() { getCertificatesNoClone(); if (certs == null) { @@ -259,16 +278,26 @@ return null; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the receiver's location. + * + * + * @return URL the receiver's URL + */ public final URL getLocation() { return location; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to .equals must + * answer the same value for this method. + * + * + * @return int the receiver's hash. + * + * @see #equals + */ public int hashCode() { // // hashCode() is undocumented there. Should we also use certs[i] to @@ -277,9 +306,15 @@ return location == null ? 0 : location.hashCode(); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument code source is implied by the receiver. + * + * + * @return boolean true if the argument code source is + * implied by the receiver, and false if it is not. + * @param cs + * CodeSource the code source to check + */ public boolean implies(CodeSource cs) { // // Here, javadoc:N refers to the appropriate item in the API spec for @@ -426,9 +461,13 @@ return true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * + * @return a printable representation for the receiver. + */ public String toString() { //FIXME 1.5 StringBuffer => StringBuilder StringBuffer buf = new StringBuffer(); Index: modules/security/src/main/java/common/java/security/DigestException.java =================================================================== --- modules/security/src/main/java/common/java/security/DigestException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/DigestException.java (working copy) @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents exceptions for message digest computation. * */ public class DigestException extends GeneralSecurityException { @@ -32,16 +33,22 @@ */ private static final long serialVersionUID = 5821450303093652515L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public DigestException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public DigestException() { } Index: modules/security/src/main/java/common/java/security/MessageDigestSpi.java =================================================================== --- modules/security/src/main/java/common/java/security/MessageDigestSpi.java (revision 395586) +++ modules/security/src/main/java/common/java/security/MessageDigestSpi.java (working copy) @@ -23,11 +23,16 @@ import java.nio.ByteBuffer; + /** - * @com.intel.drl.spec_ref + * This class is a Service Provider Interface (therefore the Spi suffix) for + * digest algorithms to be supplied by providers. Examples of digest algorithms + * are MD5 and SHA. * + * A digest is a secure hash function for a stream of bytes, like a fingerprint + * for the stream of bytes. + * */ - public abstract class MessageDigestSpi { /** Index: modules/security/src/main/java/common/java/security/Guard.java =================================================================== --- modules/security/src/main/java/common/java/security/Guard.java (revision 395586) +++ modules/security/src/main/java/common/java/security/Guard.java (working copy) @@ -21,8 +21,10 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This interface is implemented by objects which wish to control access to + * other objects. * */ public interface Guard { Index: modules/security/src/main/java/common/java/security/cert/CRLException.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CRLException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CRLException.java (working copy) @@ -34,16 +34,20 @@ */ private static final long serialVersionUID = -6694728944094197147L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * @param msg + * String The detail message for the exception. + */ public CRLException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + */ public CRLException() { } Index: modules/security/src/main/java/common/java/security/cert/CertificateException.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CertificateException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CertificateException.java (working copy) @@ -24,8 +24,7 @@ import java.security.GeneralSecurityException; /** - * @com.intel.drl.spec_ref - * + * This class represents a general certificate exception. */ public class CertificateException extends GeneralSecurityException { @@ -35,18 +34,20 @@ */ private static final long serialVersionUID = 3192535253797119798L; - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * @param msg + * String The detail message for the exception. + */ public CertificateException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Constructs a new instance of this class with its walkback filled in. + */ public CertificateException() { } Index: modules/security/src/main/java/common/java/security/cert/CRL.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CRL.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CRL.java (working copy) @@ -21,9 +21,12 @@ package java.security.cert; + /** - * @com.intel.drl.spec_ref + * This class represents Certificate Revocation Lists (CRLs). They are used to + * indicate that a given Certificate has expired already. * + * @see CertificateFactory */ public abstract class CRL { // The CRL type @@ -36,20 +39,31 @@ this.type = type; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the type of this CRL. + * + * @return String the type of this CRL. + */ public final String getType() { return type; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers if a given Certificate has been revoked or not. + * + * @param cert + * Certificate The Certificate to test + * + * @return true if the certificate has been revoked false if the certificate + * has not been revoked yet + */ public abstract boolean isRevoked(Certificate cert); - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return a printable representation for the receiver. + */ public abstract String toString(); } Index: modules/security/src/main/java/common/java/security/cert/Certificate.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/Certificate.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/Certificate.java (working copy) @@ -34,8 +34,9 @@ import java.util.Arrays; /** - * @com.intel.drl.spec_ref - * + * Abstract class to represent identity certificates. It represents a way to + * verify the binding of a Principal and its public key. Examples are X.509, + * PGP, and SDSI. */ public abstract class Certificate implements Serializable { /** @@ -53,16 +54,27 @@ this.type = type; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the certificate type represented by the receiver. + * + * @return the certificate type represented by the receiver. + */ public final String getType() { return type; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. The + * implementation in Object answers true only if the argument is the exact + * same object as the receiver (==). + * + * @param other + * the object to compare with this object + * @return true if the object is the same as this object + * false if it is different from this object + * @see #hashCode + */ public boolean equals(Object other) { // obj equal to itself if (this == other) { @@ -80,9 +92,15 @@ return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to equals must + * answer the same value for this method. + * + * @return the receiver's hash + * + * @see #equals + */ public int hashCode() { try { byte[] encoded = getEncoded(); @@ -96,14 +114,31 @@ } } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the encoded representation for this certificate. + * + * @return the encoded representation for this certificate. + */ public abstract byte[] getEncoded() throws CertificateEncodingException; - /** - * @com.intel.drl.spec_ref - */ + /** + * Verifies that this certificate was signed with the given public key. + * + * @param key + * PublicKey public key for which verification should be + * performed. + * + * @exception CertificateException + * if encoding errors are detected + * @exception NoSuchAlgorithmException + * if an unsupported algorithm is detected + * @exception InvalidKeyException + * if an invalid key is detected + * @exception NoSuchProviderException + * if there is no default provider + * @exception SignatureException + * if signature errors are detected + */ public abstract void verify(PublicKey key) throws CertificateException, NoSuchAlgorithmException, @@ -111,9 +146,27 @@ NoSuchProviderException, SignatureException; - /** - * @com.intel.drl.spec_ref - */ + /** + * Verifies that this certificate was signed with the given public key. Uses + * the signature algorithm given by the provider. + * + * @param key + * PublicKey public key for which verification should be + * performed. + * @param sigProvider + * String the name of the signature provider. + * + * @exception CertificateException + * if encoding errors are detected + * @exception NoSuchAlgorithmException + * if an unsupported algorithm is detected + * @exception InvalidKeyException + * if an invalid key is detected + * @exception NoSuchProviderException + * if there is no default provider + * @exception SignatureException + * if signature errors are detected + */ public abstract void verify(PublicKey key, String sigProvider) throws CertificateException, NoSuchAlgorithmException, @@ -121,14 +174,19 @@ NoSuchProviderException, SignatureException; - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return a printable representation for the receiver. + */ public abstract String toString(); - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the public key corresponding to this certificate. + * + * @return the public key corresponding to this certificate. + */ public abstract PublicKey getPublicKey(); /** Index: modules/security/src/main/java/common/java/security/cert/CertificateEncodingException.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CertificateEncodingException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CertificateEncodingException.java (working copy) @@ -21,9 +21,9 @@ package java.security.cert; + /** - * @com.intel.drl.spec_ref - * + * This class represents an encoding exception for a certificate. */ public class CertificateEncodingException extends CertificateException { /** @@ -31,18 +31,20 @@ */ private static final long serialVersionUID = 6219492851589449162L; - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * @param msg + * String The detail message for the exception. + */ public CertificateEncodingException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Constructs a new instance of this class with its walkback filled in. + */ public CertificateEncodingException() { } Index: modules/security/src/main/java/common/java/security/cert/CertificateFactory.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CertificateFactory.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CertificateFactory.java (working copy) @@ -34,8 +34,7 @@ /** - * @com.intel.drl.spec_ref - * + * This class provides the functionality of a certificate factory algorithm. */ public class CertificateFactory { @@ -67,12 +66,18 @@ } /** - * @com.intel.drl.spec_ref + * Answers a new CertificateFactory of the given type. * - * throws CertificateException using NoSuchAlgorithmException information + * @param type + * java.lang.String Type of certificate desired + * @return CertificateFactory a concrete implementation for the certificate + * type desired. * - * throws NullPointerException if algorithm is null (instead of - * CertificateException as in 1.4 release) + * @exception CertificateException + * If the type cannot be found + * + * @exception NullPointerException + * If the type is null */ public static final CertificateFactory getInstance(String type) throws CertificateException { @@ -110,12 +115,21 @@ } /** - * @com.intel.drl.spec_ref + * Answers a new CertificateFactory of the given type. * - * throws CertificateException using NoSuchAlgorithmException information + * @param type + * java.lang.String Type of certificatem desired + * @param provider + * java.security.Provider Provider which has to implement the + * algorithm + * @return CertificateFactory a concrete implementation for the certificate + * type desired. * - * throws NullPointerException if algorithm is null (instead of - * CertificateException as in 1.4 release) + * @exception CertificateException + * If the type cannot be found + * + * @exception NullPointerException + * If algorithm is null */ public static final CertificateFactory getInstance(String type, Provider provider) throws CertificateException { @@ -137,21 +151,35 @@ } /** - * @com.intel.drl.spec_ref + * Returns the Provider of the certificate factory represented by the + * receiver. + * + * @return Provider an instance of a subclass of java.security.Provider */ public final Provider getProvider() { return provider; } /** - * @com.intel.drl.spec_ref + * Returns the Certificate type + * + * @return String type of certificate being used */ public final String getType() { return type; } /** - * @com.intel.drl.spec_ref + * Generates and initializes a Certificate from data from the + * provided input stream. + * + * @param inStream + * InputStream Stream from where data is read to create the + * Certificate + * + * @return Certificate an initialized Certificate + * @exception CertificateException + * if parsing problems are detected */ public final Certificate generateCertificate(InputStream inStream) throws CertificateException { @@ -159,14 +187,26 @@ } /** - * @com.intel.drl.spec_ref + * Returns an Iterator over the supported CertPath encodings (as Strings). + * The first element is the default encoding. + * + * @return Iterator Iterator over supported CertPath encodings (as Strings) */ public final Iterator getCertPathEncodings() { return spiImpl.engineGetCertPathEncodings(); } /** - * @com.intel.drl.spec_ref + * Generates a CertPath from data from the provided + * InputStream. The default encoding is assumed. + * + * @param inStream + * InputStream with PKCS7 or PkiPath encoded data + * + * @return CertPath a CertPath initialized from the provided data + * + * @throws CertificateException + * if parsing problems are detected */ public final CertPath generateCertPath(InputStream inStream) throws CertificateException { @@ -178,7 +218,22 @@ } /** - * @com.intel.drl.spec_ref + * Generates a CertPath from data from the provided + * InputStream. The encoding is that specified by the + * encoding parameter. + * + * @param inStream + * InputStream containing certificate path data in specified + * encoding + * @param encoding + * encoding of the data in the input stream + * + * @return CertPath a CertPath initialized from the provided data + * + * @throws CertificateException + * if parsing problems are detected + * @throws UnsupportedOperationException + * if the provider does not implement this method */ public final CertPath generateCertPath(InputStream inStream, String encoding) throws CertificateException { @@ -186,7 +241,19 @@ } /** - * @com.intel.drl.spec_ref + * Generates a CertPath from the provided List of + * Certificates. The encoding is the default encoding. + * + * @param certificates + * List containing certificates in a format supported by the + * CertificateFactory + * + * @return CertPath a CertPath initialized from the provided data + * + * @throws CertificateException + * if parsing problems are detected + * @throws UnsupportedOperationException + * if the provider does not implement this method */ public final CertPath generateCertPath(List certificates) throws CertificateException { @@ -194,7 +261,16 @@ } /** - * @com.intel.drl.spec_ref + * Generates and initializes a collection of Certificates from + * data from the provided input stream. + * + * @param inStream + * InputStream Stream from where data is read to create the + * Certificates + * + * @return Collection an initialized collection of Certificates + * @exception CertificateException + * if parsing problems are detected */ public final Collection generateCertificates(InputStream inStream) throws CertificateException { @@ -202,14 +278,32 @@ } /** - * @com.intel.drl.spec_ref + * Generates and initializes a Certificate Revocation List from data from + * the provided input stream. + * + * @param inStream + * InputStream Stream from where data is read to create the CRL + * + * @return CRL an initialized Certificate Revocation List + * @exception CRLException + * if parsing problems are detected */ public final CRL generateCRL(InputStream inStream) throws CRLException { return spiImpl.engineGenerateCRL(inStream); } /** - * @com.intel.drl.spec_ref + * Generates and initializes a collection of Certificate Revocation List + * from data from the provided input stream. + * + * @param inStream + * InputStream Stream from where data is read to create the CRLs + * + * @return Collection an initialized collection of Certificate Revocation + * List + * @exception CRLException + * if parsing problems are detected + * */ public final Collection generateCRLs(InputStream inStream) throws CRLException { Index: modules/security/src/main/java/common/java/security/cert/CertPath.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CertPath.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CertPath.java (working copy) @@ -30,8 +30,17 @@ import java.util.List; /** - * @com.intel.drl.spec_ref + * An immutable certificate path that can be validated. All certificates in the + * path are of the same type (i.e., X509). * + * A CertPath can be represented as a byte array in at least one + * supported encoding when serialized. + * + * When a List of the certificates is obtained it must be + * immutable. + * + * A CertPath must be thread-safe without requiring coordinated + * access. */ public abstract class CertPath implements Serializable { /** @@ -48,16 +57,24 @@ this.type = type; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Returns the type of Certificate in the + * CertPath + * + * @return Certificate type + */ public String getType() { return type; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Returns true if Certificates in the list are the same + * type and the lists are equal (and by implication the certificates + * contained within are the same). + * + * @param other + * CertPath to be compared for equality + */ public boolean equals(Object other) { if (this == other) { return true; @@ -73,18 +90,27 @@ return false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Overrides Object.hashCode() Defined as: hashCode = 31 * + * path.getType().hashCode() + path.getCertificates().hashCode(); + * + * @return hash code for CertPath object + */ public int hashCode() { int hash = getType().hashCode(); hash = hash*31 + getCertificates().hashCode(); return hash; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Returns a String representation of the + * CertPath + * Certificates. It is the result of + * calling toString on all Certificates in + * the List. Certificates + * + * @return string representation of CertPath + */ public String toString() { StringBuffer sb = new StringBuffer(getType()); sb.append(" Cert Path, len="); @@ -103,24 +129,41 @@ } /** - * @com.intel.drl.spec_ref + * Returns an immutable List of the Certificates contained + * in the CertPath. + * + * @return list of Certificates in the CertPath */ public abstract List getCertificates(); /** - * @com.intel.drl.spec_ref + * Returns an encoding of the CertPath using the default + * encoding + * + * @return default encoding of the CertPath + * @throws CertificateEncodingException */ public abstract byte[] getEncoded() throws CertificateEncodingException; /** - * @com.intel.drl.spec_ref + * Returns an encoding of the CertPath using the specified + * encoding + * + * @param encoding + * encoding that should be generated + * @return default encoding of the CertPath + * @throws CertificateEncodingException */ public abstract byte[] getEncoded(String encoding) throws CertificateEncodingException; /** - * @com.intel.drl.spec_ref + * Return an Iterator over the supported encodings for a + * representation of the certificate path. + * + * @return Iterator over supported encodings (as + * Strings) */ public abstract Iterator getEncodings(); Index: modules/security/src/main/java/common/java/security/cert/CertificateExpiredException.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CertificateExpiredException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CertificateExpiredException.java (working copy) @@ -21,9 +21,9 @@ package java.security.cert; + /** - * @com.intel.drl.spec_ref - * + * This class indicates that a given certificate has expired. */ public class CertificateExpiredException extends CertificateException { @@ -33,18 +33,20 @@ */ private static final long serialVersionUID = 9071001339691533771L; - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * @param msg + * String The detail message for the exception. + */ public CertificateExpiredException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - * - */ + /** + * Constructs a new instance of this class with its walkback filled in. + */ public CertificateExpiredException() { } } \ No newline at end of file Index: modules/security/src/main/java/common/java/security/cert/CertificateNotYetValidException.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CertificateNotYetValidException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CertificateNotYetValidException.java (working copy) @@ -21,9 +21,9 @@ package java.security.cert; + /** - * @com.intel.drl.spec_ref - * + * This class indicates that a given certificate is not valid yet. */ public class CertificateNotYetValidException extends CertificateException { /** @@ -31,16 +31,20 @@ */ private static final long serialVersionUID = 4355919900041064702L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * @param msg + * String The detail message for the exception. + */ public CertificateNotYetValidException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + */ public CertificateNotYetValidException() { } } \ No newline at end of file Index: modules/security/src/main/java/common/java/security/cert/CertificateParsingException.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CertificateParsingException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CertificateParsingException.java (working copy) @@ -21,9 +21,9 @@ package java.security.cert; + /** - * @com.intel.drl.spec_ref - * + * This class indicates that a given certificate could not be parsed. */ public class CertificateParsingException extends CertificateException { @@ -32,16 +32,20 @@ */ private static final long serialVersionUID = -7989222416793322029L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * @param msg + * String The detail message for the exception. + */ public CertificateParsingException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + */ public CertificateParsingException() { } Index: modules/security/src/main/java/common/java/security/cert/CertificateFactorySpi.java =================================================================== --- modules/security/src/main/java/common/java/security/cert/CertificateFactorySpi.java (revision 395586) +++ modules/security/src/main/java/common/java/security/cert/CertificateFactorySpi.java (working copy) @@ -27,44 +27,88 @@ import java.util.List; /** - * @com.intel.drl.spec_ref - * + * This class is a Service Provider Interface (therefore the Spi suffix) for + * certificate factories to be supplied by providers. */ public abstract class CertificateFactorySpi { /** - * @com.intel.drl.spec_ref + * Constructs a new instance of this class. */ public CertificateFactorySpi() { } /** - * @com.intel.drl.spec_ref + * Generates and initializes a Certificate from data from the + * provided input stream. + * + * @param inStream + * InputStream Stream from where data is read to create the + * Certificate + * + * @return Certificate an initialized Certificate + * @exception CertificateException + * if parsing problems are detected */ public abstract Certificate engineGenerateCertificate(InputStream inStream) throws CertificateException; /** - * @com.intel.drl.spec_ref + * Generates and initializes a collection of Certificates from + * data from the provided input stream. + * + * @param inStream + * InputStream Stream from where data is read to create the + * Certificates + * + * @return Collection an initialized collection of Certificates + * @exception CertificateException + * if parsing problems are detected */ public abstract Collection engineGenerateCertificates(InputStream inStream) throws CertificateException; /** - * @com.intel.drl.spec_ref + * Generates and initializes a Certificate Revocation List from data from + * the provided input stream. + * + * @param inStream + * InputStream Stream from where data is read to create the CRL + * + * @return CRL an initialized Certificate Revocation List + * @exception CRLException + * if parsing problems are detected */ public abstract CRL engineGenerateCRL(InputStream inStream) throws CRLException; /** - * @com.intel.drl.spec_ref + * Generates and initializes a collection of Certificate Revocation List + * from data from the provided input stream. + * + * @param inStream + * InputStream Stream from where data is read to create the CRLs + * + * @return Collection an initialized collection of Certificate Revocation + * List + * @exception CRLException + * if parsing problems are detected */ public abstract Collection engineGenerateCRLs(InputStream inStream) throws CRLException; /** - * @com.intel.drl.spec_ref + * Generates a CertPath from data from the provided + * InputStream. The default encoding is assumed. + * + * @param inStream + * InputStream with PKCS7 or PkiPath encoded data + * + * @return CertPath a CertPath initialized from the provided data + * + * @throws CertificateException + * if parsing problems are detected */ public CertPath engineGenerateCertPath(InputStream inStream) throws CertificateException { @@ -73,7 +117,22 @@ } /** - * @com.intel.drl.spec_ref + * Generates a CertPath from data from the provided + * InputStream. The encoding is that specified by the + * encoding parameter. + * + * @param inStream + * InputStream containing certificate path data in specified + * encoding + * @param encoding + * encoding of the data in the input stream + * + * @return CertPath a CertPath initialized from the provided data + * + * @throws CertificateException + * if parsing problems are detected + * @throws UnsupportedOperationException + * if the provider does not implement this method */ public CertPath engineGenerateCertPath(InputStream inStream, String encoding) throws CertificateException { @@ -82,7 +141,19 @@ } /** - * @com.intel.drl.spec_ref + * Generates a CertPath from the provided List of + * Certificates. The encoding is the default encoding. + * + * @param certificates + * List containing certificates in a format supported by the + * CertificateFactory + * + * @return CertPath a CertPath initialized from the provided data + * + * @throws CertificateException + * if parsing problems are detected + * @throws UnsupportedOperationException + * if the provider does not implement this method */ public CertPath engineGenerateCertPath(List certificates) throws CertificateException { @@ -91,7 +162,10 @@ } /** - * @com.intel.drl.spec_ref + * Returns an Iterator over the supported CertPath encodings (as Strings). + * The first element is the default encoding. + * + * @return Iterator Iterator over supported CertPath encodings (as Strings) */ public Iterator engineGetCertPathEncodings() { throw new UnsupportedOperationException( Index: modules/security/src/main/java/common/java/security/ProtectionDomain.java =================================================================== --- modules/security/src/main/java/common/java/security/ProtectionDomain.java (revision 395586) +++ modules/security/src/main/java/common/java/security/ProtectionDomain.java (working copy) @@ -22,7 +22,11 @@ package java.security; /** - * @com.intel.drl.spec_ref + * This class represents a domain in which classes from the same source (URL) + * and signed by the same keys are stored. All the classes inside are given the + * same permissions. + *

+ * Note: a class can only belong to one and only one protection domain. */ public class ProtectionDomain { @@ -42,9 +46,13 @@ // permissions, true otherwise. private boolean dynamicPerms; - /** - * @com.intel.drl.spec_ref - */ + /** + * Contructs a protection domain from the given code source and the + * permissions that that should be granted to the classes which are + * encapsulated in it. + * @param cs + * @param permissions + */ public ProtectionDomain(CodeSource cs, PermissionCollection permissions) { this.codeSource = cs; if (permissions != null) { @@ -56,9 +64,23 @@ //dynamicPerms = false; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Contructs a protection domain from the given code source and the + * permissions that that should be granted to the classes which are + * encapsulated in it. + * + * This constructor also allows the association of a ClassLoader and group + * of Principals. + * + * @param cs + * the CodeSource associated with this domain + * @param permissions + * the Permissions associated with this domain + * @param cl + * the ClassLoader associated with this domain + * @param principals + * the Principals associated with this domain + */ public ProtectionDomain(CodeSource cs, PermissionCollection permissions, ClassLoader cl, Principal[] principals) { this.codeSource = cs; @@ -75,30 +97,41 @@ dynamicPerms = true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Returns the ClassLoader associated with the ProtectionDomain + * + * @return ClassLoader associated ClassLoader + */ public final ClassLoader getClassLoader() { return classLoader; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the code source of this domain. + * + * @return java.security.CodeSource the code source of this domain + */ public final CodeSource getCodeSource() { return codeSource; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the permissions that should be granted to the classes which are + * encapsulated in this domain. + * + * @return java.security.PermissionCollection collection of permissions + * associated with this domain. + */ public final PermissionCollection getPermissions() { return permissions; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Returns the Principals associated with this ProtectionDomain. A change to + * the returned array will not impact the ProtectionDomain. + * + * @return Principals[] Principals associated with the ProtectionDomain. + */ public final Principal[] getPrincipals() { if( principals == null ) { return new Principal[0]; @@ -108,9 +141,16 @@ return tmp; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Determines whether the permission collection of this domain implies the + * argument permission. + * + * + * @return boolean true if this permission collection implies the argument + * and false otherwise. + * @param permission + * java.security.Permission the permission to check. + */ public boolean implies(Permission permission) { // First, test with the Policy, as the default Policy.implies() // checks for both dynamic and static collections of the @@ -127,9 +167,12 @@ return permissions == null ? false : permissions.implies(permission); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return String a printable representation for the receiver. + */ public String toString() { //FIXME: 1.5 use StreamBuilder here StringBuffer buf = new StringBuffer(200); Index: modules/security/src/main/java/common/java/security/SecurityPermission.java =================================================================== --- modules/security/src/main/java/common/java/security/SecurityPermission.java (revision 395586) +++ modules/security/src/main/java/common/java/security/SecurityPermission.java (working copy) @@ -21,8 +21,10 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * SecurityPermission objects guard access to the mechanisms which implement + * security. Security permissions have names, but not actions. * */ public final class SecurityPermission extends BasicPermission { @@ -32,16 +34,25 @@ */ private static final long serialVersionUID = 5236109936224050470L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Creates an instance of this class with the given name. + * + * @param name + * String the name of the new permission. + */ public SecurityPermission(String name) { super(name); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Creates an instance of this class with the given name and action list. + * The action list is ignored. + * + * @param name + * String the name of the new permission. + * @param action + * String ignored. + */ public SecurityPermission(String name, String action) { super(name, action); } Index: modules/security/src/main/java/common/java/security/GeneralSecurityException.java =================================================================== --- modules/security/src/main/java/common/java/security/GeneralSecurityException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/GeneralSecurityException.java (working copy) @@ -21,8 +21,10 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents the general security exception. Subclasses will + * represents specific security problems. * */ public class GeneralSecurityException extends Exception { @@ -31,16 +33,22 @@ */ private static final long serialVersionUID = 894798122053539237L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public GeneralSecurityException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public GeneralSecurityException() { } Index: modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java =================================================================== --- modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/UnrecoverableKeyException.java (working copy) @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class represents exceptions if a key cannot be found in the keystore. * */ public class UnrecoverableKeyException extends GeneralSecurityException { @@ -32,16 +33,22 @@ */ private static final long serialVersionUID = 7275063078190151277L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public UnrecoverableKeyException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public UnrecoverableKeyException() { } } \ No newline at end of file Index: modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java =================================================================== --- modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java (working copy) @@ -21,9 +21,12 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Instances of this class are thrown when an attempt is made to access an + * algorithm which is not provided by the library. * + * @see Throwable */ public class NoSuchAlgorithmException extends GeneralSecurityException { @@ -32,16 +35,22 @@ */ private static final long serialVersionUID = -7443947487218346562L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public NoSuchAlgorithmException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public NoSuchAlgorithmException() { } Index: modules/security/src/main/java/common/java/security/NoSuchProviderException.java =================================================================== --- modules/security/src/main/java/common/java/security/NoSuchProviderException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/NoSuchProviderException.java (working copy) @@ -21,9 +21,13 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Instances of this class are thrown when an attempt is made to access a + * provider by name which is not currently available. * + * + * @see Throwable */ public class NoSuchProviderException extends GeneralSecurityException { /** @@ -31,16 +35,21 @@ */ private static final long serialVersionUID = 8488111756688534474L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * @param msg + * String The detail message for the exception. + */ public NoSuchProviderException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public NoSuchProviderException() { } } \ No newline at end of file Index: modules/security/src/main/java/common/java/security/SecureRandomSpi.java =================================================================== --- modules/security/src/main/java/common/java/security/SecureRandomSpi.java (revision 395586) +++ modules/security/src/main/java/common/java/security/SecureRandomSpi.java (working copy) @@ -24,10 +24,10 @@ import java.io.Serializable; /** - * @com.intel.drl.spec_ref + * This class is a Service Provider Interface (therefore the Spi suffix) for + * secure random number generation algorithms to be supplied by providers. * */ - public abstract class SecureRandomSpi implements Serializable { /** Index: modules/security/src/main/java/common/java/security/InvalidParameterException.java =================================================================== --- modules/security/src/main/java/common/java/security/InvalidParameterException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/InvalidParameterException.java (working copy) @@ -21,8 +21,9 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This exception is thrown when an invalid parameter is passed to a method. * */ public class InvalidParameterException extends IllegalArgumentException { @@ -32,16 +33,22 @@ */ private static final long serialVersionUID = -857968536935667808L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public InvalidParameterException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public InvalidParameterException() { } } \ No newline at end of file Index: modules/security/src/main/java/common/java/security/KeyException.java =================================================================== --- modules/security/src/main/java/common/java/security/KeyException.java (revision 395586) +++ modules/security/src/main/java/common/java/security/KeyException.java (working copy) @@ -21,9 +21,14 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * This class is the superclass of all classes which represent problems with + * keys. * + * + * @see Throwable + * @see Error */ public class KeyException extends GeneralSecurityException { @@ -32,16 +37,22 @@ */ private static final long serialVersionUID = -7483676942812432108L; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback and message + * filled in. + * + * + * @param msg + * String The detail message for the exception. + */ public KeyException(String msg) { super(msg); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class with its walkback filled in. + * + */ public KeyException() { } Index: modules/security/src/main/java/common/java/security/AllPermission.java =================================================================== --- modules/security/src/main/java/common/java/security/AllPermission.java (revision 395586) +++ modules/security/src/main/java/common/java/security/AllPermission.java (working copy) @@ -28,8 +28,11 @@ import java.util.Enumeration; import java.util.NoSuchElementException; + /** - * @com.intel.drl.spec_ref + * Subclass of Permission whose instances imply all other permissions. Granting + * this permission is equivalent to disabling security. + * */ public final class AllPermission extends Permission { @@ -39,51 +42,87 @@ // Actions name private static final String ALL_ACTIONS = ""; - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class. The two argument version is + * provided for class Policy so that it has a consistant call + * pattern across all Permissions. The name and action list are both + * ignored. + * + * @param name + * java.lang.String ignored. + * @param actions + * java.lang.String ignored. + */ public AllPermission(String name, String actions) { super(ALL_PERMISSIONS); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Constructs a new instance of this class. + */ public AllPermission() { super(ALL_PERMISSIONS); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Compares the argument to the receiver, and answers true if they represent + * the same object using a class specific comparison. All + * AllPermissions are equal to eachother. + * + * @param obj + * the object to compare with this object + * @return true if the object is the same as this object + * false if it is different from this object + * @see #hashCode + */ public boolean equals(Object obj) { return (obj instanceof AllPermission); } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers an integer hash code for the receiver. Any two objects which + * answer true when passed to equals must + * answer the same value for this method. + * + * @return the receiver's hash + * + * @see #equals + */ public int hashCode() { return 1; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers the actions associated with the receiver. Since AllPermission + * objects allow all actions, answer with the string "". + * + * @return String the actions associated with the receiver. + */ public String getActions() { return ALL_ACTIONS; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * AllPermission objects imply all other permissions. + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { return true; } - /** - * @com.intel.drl.spec_ref - */ + /** + * Answers a new PermissionCollection for holding permissions of this class. + * Answer null if any permission collection can be used. + * + * @return a new PermissionCollection or null + * + * @see java.security.BasicPermissionCollection + */ public PermissionCollection newPermissionCollection() { return new AllPermissionCollection(); } @@ -165,9 +204,15 @@ } } - /** - * Returns true if this collection is not empty. - */ + /** + * Indicates whether the argument permission is implied by the receiver. + * AllPermission objects imply all other permissions. + * + * @return boolean true if the argument permission is implied + * by the receiver, and false if it is not. + * @param permission + * java.security.Permission the permission to check + */ public boolean implies(Permission permission) { return all != null; } Index: modules/security/src/main/java/common/java/security/MessageDigest.java =================================================================== --- modules/security/src/main/java/common/java/security/MessageDigest.java (revision 395586) +++ modules/security/src/main/java/common/java/security/MessageDigest.java (working copy) @@ -97,8 +97,20 @@ } /** - * @com.intel.drl.spec_ref - * + * Answers a new MessageDigest which is capable of running the algorithm + * described by the argument. The result will be an instance of a subclass + * of MessageDigest which implements that algorithm. + * + * + * @param algorithm + * java.lang.String Name of the algorithm desired + * @param provider + * Provider Provider which has to implement the algorithm + * @return MessageDigest a concrete implementation for the algorithm + * desired. + * + * @exception NoSuchAlgorithmException + * If the algorithm cannot be found */ public static MessageDigest getInstance(String algorithm, Provider provider) throws NoSuchAlgorithmException { @@ -125,16 +137,23 @@ } /** - * @com.intel.drl.spec_ref - * + * Puts the receiver back in an initial state, such that it is ready to + * compute a new hash. + * + * @see java.security.MessageDigest.Wrapper#engineReset() */ public void reset() { engineReset(); } /** - * @com.intel.drl.spec_ref - * + * Includes the argument in the hash value computed + * by the receiver. + * + * @param arg0 byte + * the byte to feed to the hash algorithm + * + * @see #reset() */ public void update(byte arg0) { engineUpdate(arg0); @@ -165,8 +184,12 @@ } /** - * @com.intel.drl.spec_ref - * + * Computes and answers the final hash value that the receiver represents. + * After the digest is computed the receiver is reset. + * + * @return the hash the receiver computed + * + * @see #reset */ public byte[] digest() { return engineDigest(); @@ -195,16 +218,25 @@ } /** - * @com.intel.drl.spec_ref - * + * Answers a string containing a concise, human-readable description of the + * receiver. + * + * @return a printable representation for the receiver. */ public String toString() { return "MESSAGE DIGEST " + algorithm; } /** - * @com.intel.drl.spec_ref - * + * Does a simply byte-per-byte compare of the two digests. + * + * @param digesta + * One of the digests to compare + * @param digestb + * The digest to compare to + * + * @return true if the two hashes are equal + * false if the two hashes are not equal */ public static boolean isEqual(byte[] digesta, byte[] digestb) { if (digesta.length != digestb.length) { @@ -219,24 +251,29 @@ } /** - * @com.intel.drl.spec_ref - * + * Answers the standard Java Security name for the algorithm being used by + * the receiver. + * + * @return String the name of the algorithm */ public final String getAlgorithm() { return algorithm; } /** - * @com.intel.drl.spec_ref - * + * Returns the Provider of the digest represented by the receiver. + * + * @return Provider an instance of a subclass of java.security.Provider */ public final Provider getProvider() { return provider; } /** - * @com.intel.drl.spec_ref - * + * Return the engine digest length in bytes. Default is 0. + * + * @return int the engine digest length in bytes + * */ public final int getDigestLength() { int l = engineGetDigestLength(); @@ -327,4 +364,4 @@ } } } -} \ No newline at end of file +} Index: modules/security/src/main/java/common/java/security/SecureRandom.java =================================================================== --- modules/security/src/main/java/common/java/security/SecureRandom.java (revision 395586) +++ modules/security/src/main/java/common/java/security/SecureRandom.java (working copy) @@ -87,8 +87,11 @@ private static transient SecureRandom internalSecureRandom; /** - * @com.intel.drl.spec_ref + * Constructs a new instance of this class. Users are encouraged to use + * getInstance() instead. * + * An implementation for the highest-priority provider is returned. The + * instance returned will not have been seeded. */ public SecureRandom() { super(0); @@ -109,8 +112,14 @@ } /** - * @com.intel.drl.spec_ref + * Constructs a new instance of this class. Users are encouraged to use + * getInstance() instead. * + * An implementation for the highest-priority provider is returned. The + * instance returned will be seeded with the parameter. + * + * @param seed + * bytes forming the seed for this generator. */ public SecureRandom(byte[] seed) { this(); @@ -165,8 +174,19 @@ } /** - * @com.intel.drl.spec_ref + * Answers a new SecureRandom which is capable of running the algorithm + * described by the argument. The result will be an instance of a subclass + * of SecureRandomSpi which implements that algorithm. * + * @param algorithm + * java.lang.String Name of the algorithm desired + * @param provider + * java.security.Provider Provider which has to implement the + * algorithm + * @return SecureRandom a concrete implementation for the algorithm desired. + * + * @exception NoSuchAlgorithmException + * If the algorithm cannot be found */ public static SecureRandom getInstance(String algorithm, String provider) throws NoSuchAlgorithmException, NoSuchProviderException { @@ -200,8 +220,9 @@ } /** - * @com.intel.drl.spec_ref + * Returns the Provider of the secure random represented by the receiver. * + * @return Provider an instance of a subclass of java.security.Provider */ public final Provider getProvider() { return provider; @@ -224,8 +245,13 @@ } /** - * @com.intel.drl.spec_ref + * Reseeds this random object with the eight bytes described by the + * representation of the long provided. * + * + * @param seed + * long Number whose representation to use to reseed the + * receiver. */ public void setSeed(long seed) { if (seed == 0) { // skip call from Random @@ -277,8 +303,12 @@ } /** - * @com.intel.drl.spec_ref + * Returns the given number of seed bytes, computed using the seed + * generation algorithm used by this class. * + * @param numBytes + * int the given number of seed bytes + * @return byte[] The seed bytes generated */ public static byte[] getSeed(int numBytes) { if (internalSecureRandom == null) { @@ -288,8 +318,12 @@ } /** - * @com.intel.drl.spec_ref + * Generates a certain number of seed bytes * + * + * @param numBytes + * int Number of seed bytes to generate + * @return byte[] The seed bytes generated */ public byte[] generateSeed(int numBytes) { return secureRandomSpi.engineGenerateSeed(numBytes); Index: modules/security/src/main/java/common/java/security/PublicKey.java =================================================================== --- modules/security/src/main/java/common/java/security/PublicKey.java (revision 395586) +++ modules/security/src/main/java/common/java/security/PublicKey.java (working copy) @@ -21,9 +21,13 @@ package java.security; + /** - * @com.intel.drl.spec_ref + * Superinterface for all specific public key interfaces * + * + * @see PublicKey + * @see PrivateKey */ public interface PublicKey extends Key { /**