You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by nd...@apache.org on 2009/04/24 04:02:46 UTC
svn commit: r768124 - in
/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth:
./ callback/ login/ x500/
Author: ndbeyer
Date: Fri Apr 24 02:02:45 2009
New Revision: 768124
URL: http://svn.apache.org/viewvc?rev=768124&view=rev
Log:
Apply modified patch for HARMONY-6174 - Javadoc for javax.security.auth.*
Modified:
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java
harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/AuthPermission.java Fri Apr 24 02:02:45 2009
@@ -21,6 +21,37 @@
import org.apache.harmony.auth.internal.nls.Messages;
+/**
+ * Governs the use of methods in this package and also its subpackages. A
+ * <i>target name</i> of the permission specifies which methods are allowed
+ * without specifying the concrete action lists. Possible target names and
+ * associated authentication permissions are:
+ *
+ * <pre>
+ * doAs invoke Subject.doAs methods.
+ * doAsPrivileged invoke the Subject.doAsPrivileged methods.
+ * getSubject invoke Subject.getSubject().
+ * getSubjectFromDomainCombiner invoke SubjectDomainCombiner.getSubject().
+ * setReadOnly invoke Subject.setReadonly().
+ * modifyPrincipals modify the set of principals
+ * associated with a Subject.
+ * modifyPublicCredentials modify the set of public credentials
+ * associated with a Subject.
+ * modifyPrivateCredentials modify the set of private credentials
+ * associated with a Subject.
+ * refreshCredential invoke the refresh method on a credential of a
+ * refreshable credential class.
+ * destroyCredential invoke the destroy method on a credential of a
+ * destroyable credential class.
+ * createLoginContext.<i>name</i> instantiate a LoginContext with the
+ * specified name. The wildcard name ('*')
+ * allows to a LoginContext of any name.
+ * getLoginConfiguration invoke the getConfiguration method of
+ * javax.security.auth.login.Configuration.
+ * refreshLoginConfiguration Invoke the refresh method of
+ * javax.security.auth.login.Configuration.
+ * </pre>
+ */
public final class AuthPermission extends BasicPermission {
private static final long serialVersionUID = 5806031445061587174L;
@@ -42,10 +73,24 @@
return name;
}
+ /**
+ * Creates an authentication permission with the specified target name.
+ *
+ * @param name
+ * the target name of this authentication permission.
+ */
public AuthPermission(String name) {
super(init(name));
}
+ /**
+ * Creates an authentication permission with the specified target name.
+ *
+ * @param name
+ * the target name of this authentication permission.
+ * @param actions
+ * this parameter is ignored and should be {@code null}.
+ */
public AuthPermission(String name, String actions) {
super(init(name), actions);
}
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/DestroyFailedException.java Fri Apr 24 02:02:45 2009
@@ -17,14 +17,26 @@
package javax.security.auth;
+/**
+ * Signals that the {@link Destroyable#destroy()} method failed.
+ */
public class DestroyFailedException extends Exception {
private static final long serialVersionUID = -7790152857282749162L;
+ /**
+ * Creates an exception of type {@code DestroyFailedException}.
+ */
public DestroyFailedException() {
super();
}
+ /**
+ * Creates an exception of type {@code DestroyFailedException}.
+ *
+ * @param message
+ * A detail message that describes the reason for this exception.
+ */
public DestroyFailedException(String message) {
super(message);
}
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Destroyable.java Fri Apr 24 02:02:45 2009
@@ -17,10 +17,27 @@
package javax.security.auth;
+/**
+ * Allows for special treatment of sensitive information, when it comes to
+ * destroying or clearing of the data.
+ */
public interface Destroyable {
+ /**
+ * Erases the sensitive information. Once an object is destroyed any calls
+ * to its methods will throw an {@code IllegalStateException}. If it does
+ * not succeed a DestroyFailedException is thrown.
+ *
+ * @throws DestroyFailedException
+ * if the information cannot be erased.
+ */
void destroy() throws DestroyFailedException;
+ /**
+ * Returns {@code true} once an object has been safely destroyed.
+ *
+ * @return whether the object has been safely destroyed.
+ */
boolean isDestroyed();
}
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/PrivateCredentialPermission.java Fri Apr 24 02:02:45 2009
@@ -27,6 +27,28 @@
import org.apache.harmony.auth.internal.nls.Messages;
+/**
+ * Protects private credential objects belonging to a {@code Subject}. It has
+ * only one action which is "read". The target name of this permission has a
+ * special syntax:
+ *
+ * <pre>
+ * targetName = CredentialClass {PrincipalClass "PrincipalName"}*
+ * </pre>
+ *
+ * First it states a credential class and is followed then by a list of one or
+ * more principals identifying the subject.
+ * <p>
+ * The principals on their part are specified as the name of the {@code
+ * Principal} class followed by the principal name in quotes. For example, the
+ * following file may define permission to read the private credentials of a
+ * principal named "Bob": "com.sun.PrivateCredential com.sun.Principal \"Bob\""
+ * <p>
+ * The syntax also allows the use of the wildcard "*" in place of {@code
+ * CredentialClass} or {@code PrincipalClass} and/or {@code PrincipalName}.
+ *
+ * @see Principal
+ */
public final class PrivateCredentialPermission extends Permission {
private static final long serialVersionUID = 5284372143517237068L;
@@ -42,6 +64,16 @@
// owners set
private transient CredOwner[] set;
+ /**
+ * Creates a new permission for private credentials specified by the target
+ * name {@code name} and an {@code action}. The action is always
+ * {@code "read"}.
+ *
+ * @param name
+ * the target name of the permission.
+ * @param action
+ * the action {@code "read"}.
+ */
public PrivateCredentialPermission(String name, String action) {
super(name);
if (READ.equalsIgnoreCase(action)) {
@@ -52,11 +84,13 @@
}
/**
- * Creates a <code>PrivateCredentialPermission</code> from the Credential Class
- * and Set of Principals
+ * Creates a {@code PrivateCredentialPermission} from the {@code Credential}
+ * class and set of principals.
*
- * @param credentialClass - credential class name
- * @param principals - principal set
+ * @param credentialClass
+ * the credential class name.
+ * @param principals
+ * the set of principals.
*/
PrivateCredentialPermission(String credentialClass, Set<Principal> principals) {
super(credentialClass);
@@ -156,6 +190,22 @@
initTargetName(getName());
}
+ /**
+ * Returns the principal's classes and names associated with this {@code
+ * PrivateCredentialPermission} as a two dimensional array. The first
+ * dimension of the array corresponds to the number of principals. The
+ * second dimension defines either the name of the {@code PrincipalClass}
+ * [x][0] or the value of {@code PrincipalName} [x][1].
+ * <p>
+ * This corresponds to the the target name's syntax:
+ *
+ * <pre>
+ * targetName = CredentialClass {PrincipalClass "PrincipalName"}*
+ * </pre>
+ *
+ * @return the principal classes and names associated with this {@code
+ * PrivateCredentialPermission}.
+ */
public String[][] getPrincipals() {
String[][] s = new String[offset][2];
@@ -172,6 +222,11 @@
return READ;
}
+ /**
+ * Returns the class name of the credential associated with this permission.
+ *
+ * @return the class name of the credential associated with this permission.
+ */
public String getCredentialClass() {
return credentialClass;
}
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/Subject.java Fri Apr 24 02:02:45 2009
@@ -38,6 +38,20 @@
import org.apache.harmony.auth.internal.nls.Messages;
+/**
+ * The central class of the {@code javax.security.auth} package representing an
+ * authenticated user or entity (both referred to as "subject"). IT defines also
+ * the static methods that allow code to be run, and do modifications according
+ * to the subject's permissions.
+ * <p>
+ * A subject has the following features:
+ * <ul>
+ * <li>A set of {@code Principal} objects specifying the identities bound to a
+ * {@code Subject} that distinguish it.</li>
+ * <li>Credentials (public and private) such as certificates, keys, or
+ * authentication proofs such as tickets</li>
+ * </ul>
+ */
public final class Subject implements Serializable {
private static final long serialVersionUID = -8308522755600156056L;
@@ -72,6 +86,10 @@
// set of public credentials
private transient SecureSet<Object> publicCredentials;
+ /**
+ * The default constructor initializing the sets of public and private
+ * credentials and principals with the empty set.
+ */
public Subject() {
super();
principals = new SecureSet<Principal>(_PRINCIPALS);
@@ -81,6 +99,23 @@
readOnly = false;
}
+ /**
+ * The constructor for the subject, setting its public and private
+ * credentials and principals according to the arguments.
+ *
+ * @param readOnly
+ * {@code true} if this {@code Subject} is read-only, thus
+ * preventing any modifications to be done.
+ * @param subjPrincipals
+ * the set of Principals that are attributed to this {@code
+ * Subject}.
+ * @param pubCredentials
+ * the set of public credentials that distinguish this {@code
+ * Subject}.
+ * @param privCredentials
+ * the set of private credentials that distinguish this {@code
+ * Subject}.
+ */
public Subject(boolean readOnly, Set<? extends Principal> subjPrincipals,
Set<?> pubCredentials, Set<?> privCredentials) {
@@ -95,6 +130,16 @@
this.readOnly = readOnly;
}
+ /**
+ * Runs the code defined by {@code action} using the permissions granted to
+ * the {@code Subject} itself and to the code as well.
+ *
+ * @param subject
+ * the distinguished {@code Subject}.
+ * @param action
+ * the code to be run.
+ * @return the {@code Object} returned when running the {@code action}.
+ */
@SuppressWarnings("unchecked")
public static Object doAs(Subject subject, PrivilegedAction action) {
@@ -103,6 +148,21 @@
return doAs_PrivilegedAction(subject, action, AccessController.getContext());
}
+ /**
+ * Run the code defined by {@code action} using the permissions granted to
+ * the {@code Subject} and to the code itself, additionally providing a more
+ * specific context.
+ *
+ * @param subject
+ * the distinguished {@code Subject}.
+ * @param action
+ * the code to be run.
+ * @param context
+ * the specific context in which the {@code action} is invoked.
+ * if {@code null} a new {@link AccessControlContext} is
+ * instantiated.
+ * @return the {@code Object} returned when running the {@code action}.
+ */
@SuppressWarnings("unchecked")
public static Object doAsPrivileged(Subject subject, PrivilegedAction action,
AccessControlContext context) {
@@ -144,6 +204,18 @@
return AccessController.doPrivileged(action, newContext);
}
+ /**
+ * Runs the code defined by {@code action} using the permissions granted to
+ * the subject and to the code itself.
+ *
+ * @param subject
+ * the distinguished {@code Subject}.
+ * @param action
+ * the code to be run.
+ * @return the {@code Object} returned when running the {@code action}.
+ * @throws PrivilegedActionException
+ * if running the {@code action} throws an exception.
+ */
@SuppressWarnings("unchecked")
public static Object doAs(Subject subject, PrivilegedExceptionAction action)
throws PrivilegedActionException {
@@ -153,6 +225,23 @@
return doAs_PrivilegedExceptionAction(subject, action, AccessController.getContext());
}
+ /**
+ * Runs the code defined by {@code action} using the permissions granted to
+ * the subject and to the code itself, additionally providing a more
+ * specific context.
+ *
+ * @param subject
+ * the distinguished {@code Subject}.
+ * @param action
+ * the code to be run.
+ * @param context
+ * the specific context in which the {@code action} is invoked.
+ * if {@code null} a new {@link AccessControlContext} is
+ * instantiated.
+ * @return the {@code Object} returned when running the {@code action}.
+ * @throws PrivilegedActionException
+ * if running the {@code action} throws an exception.
+ */
@SuppressWarnings("unchecked")
public static Object doAsPrivileged(Subject subject,
PrivilegedExceptionAction action, AccessControlContext context)
@@ -195,6 +284,17 @@
return AccessController.doPrivileged(action, newContext);
}
+ /**
+ * Checks two Subjects for equality. More specifically if the principals,
+ * public and private credentials are equal, equality for two {@code
+ * Subjects} is implied.
+ *
+ * @param obj
+ * the {@code Object} checked for equality with this {@code
+ * Subject}.
+ * @return {@code true} if the specified {@code Subject} is equal to this
+ * one.
+ */
@Override
public boolean equals(Object obj) {
@@ -216,46 +316,117 @@
return false;
}
+ /**
+ * Returns this {@code Subject}'s {@link Principal}.
+ *
+ * @return this {@code Subject}'s {@link Principal}.
+ */
public Set<Principal> getPrincipals() {
return principals;
}
+
+ /**
+ * Returns this {@code Subject}'s {@link Principal} which is a subclass of
+ * the {@code Class} provided.
+ *
+ * @param c
+ * the {@code Class} as a criteria which the {@code Principal}
+ * returned must satisfy.
+ * @return this {@code Subject}'s {@link Principal}. Modifications to the
+ * returned set of {@code Principal}s do not affect this {@code
+ * Subject}'s set.
+ */
public <T extends Principal> Set<T> getPrincipals(Class<T> c) {
return ((SecureSet<Principal>) principals).get(c);
}
+ /**
+ * Returns the private credentials associated with this {@code Subject}.
+ *
+ * @return the private credentials associated with this {@code Subject}.
+ */
public Set<Object> getPrivateCredentials() {
return privateCredentials;
}
+ /**
+ * Returns this {@code Subject}'s private credentials which are a subclass
+ * of the {@code Class} provided.
+ *
+ * @param c
+ * the {@code Class} as a criteria which the private credentials
+ * returned must satisfy.
+ * @return this {@code Subject}'s private credentials. Modifications to the
+ * returned set of credentials do not affect this {@code Subject}'s
+ * credentials.
+ */
public <T> Set<T> getPrivateCredentials(Class<T> c) {
return privateCredentials.get(c);
}
+ /**
+ * Returns the public credentials associated with this {@code Subject}.
+ *
+ * @return the public credentials associated with this {@code Subject}.
+ */
public Set<Object> getPublicCredentials() {
return publicCredentials;
}
+
+ /**
+ * Returns this {@code Subject}'s public credentials which are a subclass of
+ * the {@code Class} provided.
+ *
+ * @param c
+ * the {@code Class} as a criteria which the public credentials
+ * returned must satisfy.
+ * @return this {@code Subject}'s public credentials. Modifications to the
+ * returned set of credentials do not affect this {@code Subject}'s
+ * credentials.
+ */
public <T> Set<T> getPublicCredentials(Class<T> c) {
return publicCredentials.get(c);
}
+ /**
+ * Returns a hash code of this {@code Subject}.
+ *
+ * @return a hash code of this {@code Subject}.
+ */
@Override
public int hashCode() {
return principals.hashCode() + privateCredentials.hashCode()
+ publicCredentials.hashCode();
}
+ /**
+ * Prevents from modifications being done to the credentials and {@link
+ * Principal} sets. After setting it to read-only this {@code Subject} can
+ * not be made writable again. The destroy method on the credentials still
+ * works though.
+ */
public void setReadOnly() {
checkPermission(_READ_ONLY);
readOnly = true;
}
+ /**
+ * Returns whether this {@code Subject} is read-only or not.
+ *
+ * @return whether this {@code Subject} is read-only or not.
+ */
public boolean isReadOnly() {
return readOnly;
}
+ /**
+ * Returns a {@code String} representation of this {@code Subject}.
+ *
+ * @return a {@code String} representation of this {@code Subject}.
+ */
@Override
public String toString() {
@@ -303,6 +474,16 @@
out.defaultWriteObject();
}
+ /**
+ * Returns the {@code Subject} that was last associated with the {@code
+ * context} provided as argument.
+ *
+ * @param context
+ * the {@code context} that was associated with the
+ * {@code Subject}.
+ * @return the {@code Subject} that was last associated with the {@code
+ * context} provided as argument.
+ */
public static Subject getSubject(final AccessControlContext context) {
checkPermission(_SUBJECT);
if (context == null) {
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/SubjectDomainCombiner.java Fri Apr 24 02:02:45 2009
@@ -22,6 +22,10 @@
import java.security.ProtectionDomain;
import java.util.Set;
+/**
+ * Merges permissions based on code source and code signers with permissions
+ * granted to the specified {@link Subject}.
+ */
public class SubjectDomainCombiner implements DomainCombiner {
// subject to be associated
@@ -31,6 +35,12 @@
private static final AuthPermission _GET = new AuthPermission(
"getSubjectFromDomainCombiner"); //$NON-NLS-1$
+ /**
+ * Creates a domain combiner for the entity provided in {@code subject}.
+ *
+ * @param subject
+ * the entity to which this domain combiner is associated.
+ */
public SubjectDomainCombiner(Subject subject) {
super();
if (subject == null) {
@@ -39,6 +49,11 @@
this.subject = subject;
}
+ /**
+ * Returns the entity to which this domain combiner is associated.
+ *
+ * @return the entity to which this domain combiner is associated.
+ */
public Subject getSubject() {
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
@@ -48,6 +63,22 @@
return subject;
}
+ /**
+ * Merges the {@code ProtectionDomain} with the {@code Principal}s
+ * associated with the subject of this {@code SubjectDomainCombiner}.
+ *
+ * @param currentDomains
+ * the {@code ProtectionDomain}s associated with the context of
+ * the current thread. The domains must be sorted according to
+ * the execution order, the most recent residing at the
+ * beginning.
+ * @param assignedDomains
+ * the {@code ProtectionDomain}s from the parent thread based on
+ * code source and signers.
+ * @return a single {@code ProtectionDomain} array computed from the two
+ * provided arrays, or {@code null}.
+ * @see ProtectionDomain
+ */
public ProtectionDomain[] combine(ProtectionDomain[] currentDomains,
ProtectionDomain[] assignedDomains) {
// get array length for combining protection domains
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/Callback.java Fri Apr 24 02:02:45 2009
@@ -17,5 +17,9 @@
package javax.security.auth.callback;
+/**
+ * Defines an empty base interface for all {@code Callback}s used during
+ * authentication.
+ */
public interface Callback {
}
\ No newline at end of file
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/CallbackHandler.java Fri Apr 24 02:02:45 2009
@@ -17,8 +17,38 @@
package javax.security.auth.callback;
+import java.io.IOException;
+
+/**
+ * Needs to be implemented by classes that want to handle authentication
+ * {@link Callback}s. A single method {@link #handle(Callback[])} must be
+ * provided that checks the type of the incoming {@code Callback}s and reacts
+ * accordingly. {@code CallbackHandler}s can be installed per application. It is
+ * also possible to configure a system-default {@code CallbackHandler} by
+ * setting the {@code auth.login.defaultCallbackHandler} property in the
+ * standard {@code security.properties} file.
+ */
public interface CallbackHandler {
- void handle(Callback[] callbacks) throws java.io.IOException, UnsupportedCallbackException;
+ /**
+ * Handles the actual {@link Callback}. A {@code CallbackHandler} needs to
+ * implement this method. In the method, it is free to select which {@code
+ * Callback}s it actually wants to handle and in which way. For example, a
+ * console-based {@code CallbackHandler} might choose to sequentially ask
+ * the user for login and password, if it implements these {@code Callback}
+ * s, whereas a GUI-based one might open a single dialog window for both
+ * values. If a {@code CallbackHandler} is not able to handle a specific
+ * {@code Callback}, it needs to throw an
+ * {@link UnsupportedCallbackException}.
+ *
+ * @param callbacks
+ * the array of {@code Callback}s that need handling
+ * @throws IOException
+ * if an I/O related error occurs
+ * @throws UnsupportedCallbackException
+ * if the {@code CallbackHandler} is not able to handle a
+ * specific {@code Callback}
+ */
+ void handle(Callback[] callbacks) throws IOException, UnsupportedCallbackException;
}
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/PasswordCallback.java Fri Apr 24 02:02:45 2009
@@ -22,6 +22,10 @@
import org.apache.harmony.auth.internal.nls.Messages;
+/**
+ * Is used in conjunction with a {@link CallbackHandler} to retrieve a password
+ * when needed.
+ */
public class PasswordCallback implements Callback, Serializable {
private static final long serialVersionUID = 2267422647454909926L;
@@ -39,20 +43,49 @@
this.prompt = prompt;
}
+ /**
+ * Creates a new {@code PasswordCallback} instance.
+ *
+ * @param prompt
+ * the message that should be displayed to the user
+ * @param echoOn
+ * determines whether the user input should be echoed
+ */
public PasswordCallback(String prompt, boolean echoOn) {
super();
setPrompt(prompt);
this.echoOn = echoOn;
}
+ /**
+ * Returns the prompt that was specified when creating this {@code
+ * PasswordCallback}
+ *
+ * @return the prompt
+ */
public String getPrompt() {
return prompt;
}
+ /**
+ * Queries whether this {@code PasswordCallback} expects user input to be
+ * echoed, which is specified during the creation of the object.
+ *
+ * @return {@code true} if (and only if) user input should be echoed
+ */
public boolean isEchoOn() {
return echoOn;
}
+ /**
+ * Sets the password. The {@link CallbackHandler} that performs the actual
+ * provisioning or input of the password needs to call this method to hand
+ * back the password to the security service that requested it.
+ *
+ * @param password
+ * the password. A copy of this is stored, so subsequent changes
+ * to the input array do not affect the {@code PasswordCallback}.
+ */
public void setPassword(char[] password) {
if (password == null) {
this.inputPassword = password;
@@ -62,6 +95,15 @@
}
}
+ /**
+ * Returns the password. The security service that needs the password
+ * usually calls this method once the {@link CallbackHandler} has finished
+ * its work.
+ *
+ * @return the password. A copy of the internal password is created and
+ * returned, so subsequent changes to the internal password do not
+ * affect the result.
+ */
public char[] getPassword() {
if (inputPassword != null) {
char[] tmp = new char[inputPassword.length];
@@ -71,6 +113,9 @@
return null;
}
+ /**
+ * Clears the password stored in this {@code PasswordCallback}.
+ */
public void clearPassword() {
if (inputPassword != null) {
Arrays.fill(inputPassword, '\u0000');
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/callback/UnsupportedCallbackException.java Fri Apr 24 02:02:45 2009
@@ -17,22 +17,47 @@
package javax.security.auth.callback;
+/**
+ * Thrown when a {@link CallbackHandler} does not support a particular {@link
+ * Callback}.
+ */
public class UnsupportedCallbackException extends Exception {
private static final long serialVersionUID = -6873556327655666839L;
private Callback callback;
+ /**
+ * Creates a new exception instance and initializes it with just the
+ * unsupported {@code Callback}, but no error message.
+ *
+ * @param callback
+ * the {@code Callback}
+ */
public UnsupportedCallbackException(Callback callback) {
super();
this.callback = callback;
}
+ /**
+ * Creates a new exception instance and initializes it with both the
+ * unsupported {@code Callback} and an error message.
+ *
+ * @param callback
+ * the {@code Callback}
+ * @param message
+ * the error message
+ */
public UnsupportedCallbackException(Callback callback, String message) {
super(message);
this.callback = callback;
}
+ /**
+ * Returns the unsupported {@code Callback} that triggered this exception.
+ *
+ * @return the {@code Callback}
+ */
public Callback getCallback() {
return callback;
}
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/login/LoginException.java Fri Apr 24 02:02:45 2009
@@ -19,14 +19,25 @@
import java.security.GeneralSecurityException;
+/**
+ * Base class for exceptions that are thrown when a login error occurs.
+ */
public class LoginException extends GeneralSecurityException {
private static final long serialVersionUID = -4679091624035232488L;
+ /**
+ * Creates a new exception instance and initializes it with default values.
+ */
public LoginException() {
super();
}
+ /**
+ * Creates a new exception instance and initializes it with a given message.
+ *
+ * @param message the error message
+ */
public LoginException(String message) {
super(message);
}
Modified: harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java?rev=768124&r1=768123&r2=768124&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java (original)
+++ harmony/enhanced/classlib/trunk/modules/auth/src/main/java/common/javax/security/auth/x500/X500Principal.java Fri Apr 24 02:02:45 2009
@@ -27,19 +27,49 @@
import org.apache.harmony.auth.internal.nls.Messages;
import org.apache.harmony.security.x501.Name;
+/**
+ * Represents an X.500 principal, which holds the distinguished name of some
+ * network entity. An example of a distinguished name is {@code "O=SomeOrg,
+ * OU=SomeOrgUnit, C=US"}. The class can be instantiated from a byte representation
+ * of an object identifier (OID), an ASN.1 DER-encoded version, or a simple
+ * string holding the distinguished name. The representations must follow either
+ * RFC 2253, RFC 1779, or RFC2459.
+ */
public final class X500Principal implements Serializable, Principal {
private static final long serialVersionUID = -500463348111345721L;
+ /**
+ * Defines a constant for the canonical string format of distinguished
+ * names.
+ */
public static final String CANONICAL = "CANONICAL"; //$NON-NLS-1$
+ /**
+ * Defines a constant for the RFC 1779 string format of distinguished
+ * names.
+ */
public static final String RFC1779 = "RFC1779"; //$NON-NLS-1$
+ /**
+ * Defines a constant for the RFC 2253 string format of distinguished
+ * names.
+ */
public static final String RFC2253 = "RFC2253"; //$NON-NLS-1$
//Distinguished Name
private transient Name dn;
+ /**
+ * Creates a new X500Principal from a given ASN.1 DER encoding of a
+ * distinguished name.
+ *
+ * @param name
+ * the ASN.1 DER-encoded distinguished name
+ *
+ * @throws IllegalArgumentException
+ * if the ASN.1 DER-encoded distinguished name is incorrect
+ */
public X500Principal(byte[] name) {
super();
if (name == null) {
@@ -56,6 +86,17 @@
}
}
+ /**
+ * Creates a new X500Principal from a given ASN.1 DER encoding of a
+ * distinguished name.
+ *
+ * @param in
+ * an {@code InputStream} holding the ASN.1 DER-encoded
+ * distinguished name
+ *
+ * @throws IllegalArgumentException
+ * if the ASN.1 DER-encoded distinguished name is incorrect
+ */
public X500Principal(InputStream in) {
super();
if (in == null) {
@@ -72,6 +113,17 @@
}
}
+ /**
+ * Creates a new X500Principal from a string representation of a
+ * distinguished name.
+ *
+ * @param name
+ * the string representation of the distinguished name
+ *
+ * @throws IllegalArgumentException
+ * if the string representation of the distinguished name is
+ * incorrect
+ */
public X500Principal(String name) {
super();
if (name == null) {
@@ -99,6 +151,12 @@
return dn.getName(CANONICAL).equals(principal.dn.getName(CANONICAL));
}
+ /**
+ * Returns an ASN.1 DER-encoded representation of the distinguished name
+ * contained in this X.500 principal.
+ *
+ * @return the ASN.1 DER-encoded representation
+ */
public byte[] getEncoded() {
byte[] src = dn.getEncoded();
byte[] dst = new byte[src.length];
@@ -106,10 +164,35 @@
return dst;
}
+ /**
+ * Returns a human-readable string representation of the distinguished name
+ * contained in this X.500 principal.
+ *
+ * @return the string representation
+ */
public String getName() {
return dn.getName(RFC2253);
}
+ /**
+ * Returns a string representation of the distinguished name contained in
+ * this X.500 principal. The format of the representation can be chosen.
+ * Valid arguments are {@link #RFC1779}, {@link #RFC2253}, and
+ * {@link #CANONICAL}. The representations are specified in RFC 1779 and RFC
+ * 2253, respectively. The canonical form is based on RFC 2253, but adds
+ * some canonicalizing operations like removing leading and trailing
+ * whitespace, lower-casing the whole name, and bringing it into a
+ * normalized Unicode representation.
+ *
+ * @param format
+ * the name of the format to use for the representation
+ *
+ * @return the string representation
+ *
+ * @throws IllegalArgumentException
+ * if the {@code format} argument is not one of the three
+ * mentioned above
+ */
public String getName(String format) {
return dn.getName(format);
}