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
+ * 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 = "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 Enumerationtrue 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 Enumerationtrue 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 IteratorCertPath 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 extends Certificate> 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 extends Certificate> 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 extends CRL> 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 extends Certificate> 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 IteratorCertPath 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 extends Certificate> 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 IteratorPolicy 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 "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 {
/**