diff options
| author | The Android Open Source Project <initial-contribution@android.com> | 2008-12-17 18:03:55 -0800 |
|---|---|---|
| committer | The Android Open Source Project <initial-contribution@android.com> | 2008-12-17 18:03:55 -0800 |
| commit | dd828f42a5c83b4270d4fbf6fce2da1878f1e84a (patch) | |
| tree | fdd4b68fa1020f2b6426034c94823419a7236200 /auth/src/main | |
| parent | fdb2704414a9ed92394ada0d1395e4db86889465 (diff) | |
| download | libcore-dd828f42a5c83b4270d4fbf6fce2da1878f1e84a.zip libcore-dd828f42a5c83b4270d4fbf6fce2da1878f1e84a.tar.gz libcore-dd828f42a5c83b4270d4fbf6fce2da1878f1e84a.tar.bz2 | |
Code drop from //branches/cupcake/...@124589
Diffstat (limited to 'auth/src/main')
17 files changed, 617 insertions, 30 deletions
diff --git a/auth/src/main/java/javax/security/auth/AuthPermission.java b/auth/src/main/java/javax/security/auth/AuthPermission.java index 31f5b50..06ea3fb 100644 --- a/auth/src/main/java/javax/security/auth/AuthPermission.java +++ b/auth/src/main/java/javax/security/auth/AuthPermission.java @@ -21,6 +21,39 @@ import java.security.BasicPermission; 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> + * + * @since Android 1.0 + */ public final class AuthPermission extends BasicPermission { private static final long serialVersionUID = 5806031445061587174L; @@ -42,10 +75,24 @@ public final class AuthPermission extends BasicPermission { 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); } diff --git a/auth/src/main/java/javax/security/auth/DestroyFailedException.java b/auth/src/main/java/javax/security/auth/DestroyFailedException.java index 16e9dfb..a5438a6 100644 --- a/auth/src/main/java/javax/security/auth/DestroyFailedException.java +++ b/auth/src/main/java/javax/security/auth/DestroyFailedException.java @@ -17,14 +17,28 @@ package javax.security.auth; +/** + * Signals that the {@link Destroyable#destroy()} method failed. + * + * @since Android 1.0 + */ 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); } diff --git a/auth/src/main/java/javax/security/auth/Destroyable.java b/auth/src/main/java/javax/security/auth/Destroyable.java index a54cbe6..6194db6 100644 --- a/auth/src/main/java/javax/security/auth/Destroyable.java +++ b/auth/src/main/java/javax/security/auth/Destroyable.java @@ -17,10 +17,29 @@ package javax.security.auth; +/** + * Allows for special treatment of sensitive information, when it comes to + * destroying or clearing of the data. + * + * @since Android 1.0 + */ 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(); } diff --git a/auth/src/main/java/javax/security/auth/PrivateCredentialPermission.java b/auth/src/main/java/javax/security/auth/PrivateCredentialPermission.java index 1f5a560..d92ede5 100644 --- a/auth/src/main/java/javax/security/auth/PrivateCredentialPermission.java +++ b/auth/src/main/java/javax/security/auth/PrivateCredentialPermission.java @@ -27,6 +27,29 @@ import java.util.Set; 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 + * @since Android 1.0 + */ public final class PrivateCredentialPermission extends Permission { private static final long serialVersionUID = 5284372143517237068L; @@ -42,6 +65,16 @@ public final class PrivateCredentialPermission extends Permission { // 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 +85,13 @@ public final class PrivateCredentialPermission extends Permission { } /** - * 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 +191,22 @@ public final class PrivateCredentialPermission extends Permission { 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]. + * + * 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 +223,11 @@ public final class PrivateCredentialPermission extends Permission { 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; } diff --git a/auth/src/main/java/javax/security/auth/Subject.java b/auth/src/main/java/javax/security/auth/Subject.java index 12c2ff6..5a4cceb 100644 --- a/auth/src/main/java/javax/security/auth/Subject.java +++ b/auth/src/main/java/javax/security/auth/Subject.java @@ -38,6 +38,22 @@ import java.util.Set; 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> + * </p> + * @since Android 1.0 + */ public final class Subject implements Serializable { private static final long serialVersionUID = -8308522755600156056L; @@ -72,6 +88,10 @@ public final class Subject implements Serializable { // 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 +101,23 @@ public final class Subject implements Serializable { 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 +132,16 @@ public final class Subject implements Serializable { 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 +150,21 @@ public final class Subject implements Serializable { 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 +206,18 @@ public final class Subject implements Serializable { 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 +227,23 @@ public final class Subject implements Serializable { 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 +286,17 @@ public final class Subject implements Serializable { 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 +318,117 @@ public final class Subject implements Serializable { 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 +476,16 @@ public final class Subject implements Serializable { 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) { @@ -598,4 +781,4 @@ public final class Subject implements Serializable { } } } -}
\ No newline at end of file +} diff --git a/auth/src/main/java/javax/security/auth/SubjectDomainCombiner.java b/auth/src/main/java/javax/security/auth/SubjectDomainCombiner.java index 80f9d85..6a8f00b 100644 --- a/auth/src/main/java/javax/security/auth/SubjectDomainCombiner.java +++ b/auth/src/main/java/javax/security/auth/SubjectDomainCombiner.java @@ -22,6 +22,12 @@ import java.security.Principal; 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}. + * + * @since Android 1.0 + */ public class SubjectDomainCombiner implements DomainCombiner { // subject to be associated @@ -31,6 +37,12 @@ public class SubjectDomainCombiner implements DomainCombiner { 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 +51,11 @@ public class SubjectDomainCombiner implements DomainCombiner { 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 +65,22 @@ public class SubjectDomainCombiner implements DomainCombiner { 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 diff --git a/auth/src/main/java/javax/security/auth/callback/Callback.java b/auth/src/main/java/javax/security/auth/callback/Callback.java index 13e7574..6cf46b8 100644 --- a/auth/src/main/java/javax/security/auth/callback/Callback.java +++ b/auth/src/main/java/javax/security/auth/callback/Callback.java @@ -17,5 +17,11 @@ package javax.security.auth.callback; +/** + * Defines an empty base interface for all {@code Callback}s used during + * authentication. + * + * @since Android 1.0 + */ public interface Callback { }
\ No newline at end of file diff --git a/auth/src/main/java/javax/security/auth/callback/CallbackHandler.java b/auth/src/main/java/javax/security/auth/callback/CallbackHandler.java index ceaeba4..9ca3434 100644 --- a/auth/src/main/java/javax/security/auth/callback/CallbackHandler.java +++ b/auth/src/main/java/javax/security/auth/callback/CallbackHandler.java @@ -17,8 +17,38 @@ package javax.security.auth.callback; +/** + * 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. + * + * @since Android 1.0 + */ public interface CallbackHandler { + /** + * 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 java.io.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 java.io.IOException, UnsupportedCallbackException; } diff --git a/auth/src/main/java/javax/security/auth/callback/PasswordCallback.java b/auth/src/main/java/javax/security/auth/callback/PasswordCallback.java index e8191bf..00020fe 100644 --- a/auth/src/main/java/javax/security/auth/callback/PasswordCallback.java +++ b/auth/src/main/java/javax/security/auth/callback/PasswordCallback.java @@ -22,6 +22,12 @@ import java.util.Arrays; import org.apache.harmony.auth.internal.nls.Messages; +/** + * Is used in conjunction with a {@link CallbackHandler} to retrieve a password + * when needed. + * + * @since Android 1.0 + */ public class PasswordCallback implements Callback, Serializable { private static final long serialVersionUID = 2267422647454909926L; @@ -39,20 +45,49 @@ public class PasswordCallback implements Callback, Serializable { 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 +97,15 @@ public class PasswordCallback implements Callback, Serializable { } } + /** + * 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 +115,9 @@ public class PasswordCallback implements Callback, Serializable { return null; } + /** + * Clears the password stored in this {@code PasswordCallback}. + */ public void clearPassword() { if (inputPassword != null) { Arrays.fill(inputPassword, '\u0000'); diff --git a/auth/src/main/java/javax/security/auth/callback/UnsupportedCallbackException.java b/auth/src/main/java/javax/security/auth/callback/UnsupportedCallbackException.java index e814774..d40ff45 100644 --- a/auth/src/main/java/javax/security/auth/callback/UnsupportedCallbackException.java +++ b/auth/src/main/java/javax/security/auth/callback/UnsupportedCallbackException.java @@ -17,22 +17,49 @@ package javax.security.auth.callback; +/** + * Thrown when a {@link CallbackHandler} does not support a particular {@link + * Callback}. + * + * @since Android 1.0 + */ 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; } diff --git a/auth/src/main/java/javax/security/auth/callback/package.html b/auth/src/main/java/javax/security/auth/callback/package.html index 50073c7..5446ab8 100644 --- a/auth/src/main/java/javax/security/auth/callback/package.html +++ b/auth/src/main/java/javax/security/auth/callback/package.html @@ -5,11 +5,18 @@ <html> <body> <p> -This package provides all the classes and interfaces needed to interact with the application -in order to execute the authentification and authorization processes. -It is a classical callback mechanism: one retrieves information (i.e. for authentification -purposes) and one display some messages (for example error messages). - +This package provides classes and interfaces needed to interact with the +application in order to execute the authentification and authorization +processes. It is a classical callback mechanism: one retrieves information (i.e. +for authentification purposes) and one display some messages (for example error +messages). </p> +<p> +Note that the current implementation of this package is not complete, that is, +not compatible with desktop implementations of the Java programming language. +It contains only what was needed to make the compiler happy, that is, classes +required by other packages. +</p> +@since Android 1.0 </body> </html>
\ No newline at end of file diff --git a/auth/src/main/java/javax/security/auth/login/LoginException.java b/auth/src/main/java/javax/security/auth/login/LoginException.java index 993d5c1..a1d6ec0 100644 --- a/auth/src/main/java/javax/security/auth/login/LoginException.java +++ b/auth/src/main/java/javax/security/auth/login/LoginException.java @@ -19,14 +19,27 @@ package javax.security.auth.login; import java.security.GeneralSecurityException; +/** + * Base class for exceptions that are thrown when a login error occurs. + * + * @since Android 1.0 + */ 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); } diff --git a/auth/src/main/java/javax/security/auth/login/package.html b/auth/src/main/java/javax/security/auth/login/package.html index f8d7ab9..382b487 100644 --- a/auth/src/main/java/javax/security/auth/login/package.html +++ b/auth/src/main/java/javax/security/auth/login/package.html @@ -5,11 +5,16 @@ <html> <body> <p> -This package provides a pluggable and stackable authentication system based on ideas and concepts -from the Unix-PAM module. -New authentication methods can be specified simply via a new LoginModule and chained together -with the existing ones. - +This package provides a pluggable and stackable authentication system based on +ideas and concepts from the Unix-PAM module. New authentication methods can be +specified simply via a new LoginModule and chained together with the existing +ones. </p> +Note that the current implementation of this package is not complete, that is, +not compatible with desktop implementations of the Java programming language. +It contains only what was needed to make the compiler happy, that is, classes +required by other packages. +</p> +@since Android 1.0 </body> </html>
\ No newline at end of file diff --git a/auth/src/main/java/javax/security/auth/package.html b/auth/src/main/java/javax/security/auth/package.html index 3dd5344..2bca2db 100644 --- a/auth/src/main/java/javax/security/auth/package.html +++ b/auth/src/main/java/javax/security/auth/package.html @@ -5,14 +5,14 @@ <html> <body> <p> -This package provides all the classes and interfaces needed to implemenet and program +This package provides the classes and interfaces needed to implemenet and program different methods of users' authentification and role based users' authorization. -It integrates the previous separated JAAS package into the Java SDK. All subjects' authentification and role based authorization are strongly coupled with -the java.security file that, as always, is the ultimate arbiter of all matters secure in Java. -For example the class {@link javax.security.auth.SubjectDomainCombiner} updates the +the java.security file that, as always, is the ultimate arbiter of all matters secure in Android. +For example the class <i>javax.security.auth.SubjectDomainCombiner</i> updates the ProtectionDomains associated with the actual class with the subjects defined therein. </p> +@since Android 1.0 </body> </html> diff --git a/auth/src/main/java/javax/security/auth/x500/X500Principal.java b/auth/src/main/java/javax/security/auth/x500/X500Principal.java index a168dae..fa9dfe8 100644 --- a/auth/src/main/java/javax/security/auth/x500/X500Principal.java +++ b/auth/src/main/java/javax/security/auth/x500/X500Principal.java @@ -27,19 +27,51 @@ import java.security.Principal; 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=Google, + * OU=Android, 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. + * + * @since Android 1.0 + */ 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 +88,17 @@ public final class X500Principal implements Serializable, Principal { } } + /** + * 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 +115,17 @@ public final class X500Principal implements Serializable, Principal { } } + /** + * 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 +153,12 @@ public final class X500Principal implements Serializable, Principal { 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 +166,35 @@ public final class X500Principal implements Serializable, Principal { 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); } diff --git a/auth/src/main/java/javax/security/auth/x500/package.html b/auth/src/main/java/javax/security/auth/x500/package.html index 3a7163e..58d27ac 100644 --- a/auth/src/main/java/javax/security/auth/x500/package.html +++ b/auth/src/main/java/javax/security/auth/x500/package.html @@ -5,14 +5,14 @@ <html> <body> <p> -This package provides all the classes needed to store X.500 principals and their credentials. -The class {@link javax.security.auth.x500.X500Principal} represents such a principal. -Specifically, X500 principals are defined by such tokens (distinguished names) as O=Google, - OU=Android, C=US. - The class accepts string representations of distinguished names defined in both - specifications RFC2253 and (the older) RFC1779. OID (Object Identifiers used to encode with - the ASN.1 standard the extended attributes of distinguished name, algorithm etc.) must - follow the RFC2459 specification. +This package provides classes needed to store X.500 principals and their +credentials. </p> +Note that the current implementation of this package is not complete, that is, +not compatible with desktop implementations of the Java programming language. +It contains only what was needed to make the compiler happy, that is, classes +required by other packages. +</p> +@since Android 1.0 </body> </html> diff --git a/auth/src/main/java/org/apache/harmony/auth/internal/nls/Messages.java b/auth/src/main/java/org/apache/harmony/auth/internal/nls/Messages.java index 0722e99..511aa7a 100644 --- a/auth/src/main/java/org/apache/harmony/auth/internal/nls/Messages.java +++ b/auth/src/main/java/org/apache/harmony/auth/internal/nls/Messages.java @@ -21,6 +21,10 @@ * if this tool runs again. Better make changes in the template file. */ +// BEGIN android-note +// Redundant code has been removed and is now called from MsgHelp. +// END android-note + package org.apache.harmony.auth.internal.nls; @@ -30,8 +34,9 @@ import java.util.Locale; import java.util.MissingResourceException; import java.util.ResourceBundle; -import org.apache.harmony.kernel.vm.VM; +// BEGIN android-changed import org.apache.harmony.luni.util.MsgHelp; +// END android-changed /** * This class retrieves strings from a resource bundle and returns them, @@ -48,9 +53,11 @@ import org.apache.harmony.luni.util.MsgHelp; * */ public class Messages { - + + // BEGIN android-changed private static final String sResource = "org.apache.harmony.auth.internal.nls.messages"; + // END android-changed /** * Retrieves a message which has no arguments. @@ -60,7 +67,9 @@ public class Messages { * @return String the message for that key in the system message bundle. */ static public String getString(String msg) { + // BEGIN android-changed return MsgHelp.getString(sResource, msg); + // END android-changed } /** @@ -127,6 +136,12 @@ public class Messages { * @return String the message for that key in the system message bundle. */ static public String getString(String msg, Object[] args) { + // BEGIN android-changed return MsgHelp.getString(sResource, msg, args); + // END android-changed } -}
\ No newline at end of file + + // BEGIN android-note + // Duplicate code was dropped in favor of using MsgHelp. + // END android-note +} |