You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/28 19:01:47 UTC
svn commit: r769463 [3/9] - in
/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common:
java/security/ java/security/acl/ java/security/cert/
java/security/interfaces/ java/security/spec/ javax/security/cert/
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyRep.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyRep.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyRep.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyRep.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Vladimir N. Molotkov
-* @version $Revision$
-*/
-
package java.security;
import java.io.IOException;
@@ -36,13 +31,11 @@
import org.apache.harmony.security.internal.nls.Messages;
/**
- * @com.intel.drl.spec_ref
- *
+ * {@code KeyRep} is a standardized representation for serialized {@link Key}
+ * objects.
*/
public class KeyRep implements Serializable {
- /**
- * @com.intel.drl.spec_ref
- */
+
private static final long serialVersionUID = -4757683898830641853L;
// Key type
private final Type type;
@@ -54,7 +47,22 @@
private byte[] encoded;
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code KeyRep} with the specified arguments.
+ * The arguments should be obtained from the {@code Key} object that has to
+ * be serialized.
+ *
+ * @param type
+ * the type of the key.
+ * @param algorithm
+ * the algorithm (obtained by {@link Key#getAlgorithm()}).
+ * @param format
+ * the format of the key (obtained by {@link Key#getFormat()}).
+ * @param encoded
+ * the encoded {@code byte[]} (obtained by
+ * {@link Key#getEncoded()}).
+ * @throws NullPointerException
+ * if {@code type, algorithm, format or encoded} is {@code null}
+ * .
*/
public KeyRep(Type type,
String algorithm, String format, byte[] encoded) {
@@ -77,7 +85,25 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Resolves and returns the {@code Key} object. Three {@link Type}|format
+ * combinations are supported:
+ * <ul>
+ * <li> {@code Type.PRIVATE} | "PKCS#8" : returns a {@link PrivateKey}
+ * instance, generated from a key factory (suitable for the algorithm) that
+ * is initialized with a {@link PKCS8EncodedKeySpec} using the encoded key
+ * bytes.
+ * <li> {@code Type.SECRET} | "RAW" : returns a {@link SecretKeySpec}
+ * instance, created with the encoded key bytes and the algorithm.
+ * <li> {@code Type.PUBLIC} | "X.509": returns a {@link PublicKey} instance,
+ * generated from a key factory (suitable for the algorithm) that is
+ * initialized with a {@link X509EncodedKeySpec} using the encoded key
+ * bytes.
+ * </ul>
+ *
+ * @return the resolved {@code Key} object.
+ * @throws ObjectStreamException
+ * if the {@code Type}|format combination is not recognized, or
+ * the resolution of any key parameter fails.
*/
protected Object readResolve() throws ObjectStreamException {
switch (type) {
@@ -138,11 +164,21 @@
}
/**
- * Supported key types
+ * {@code Type} enumerates the supported key types.
*/
public static enum Type {
+
+ /**
+ * Type for secret keys.
+ */
SECRET,
+ /**
+ * Type for public keys.
+ */
PUBLIC,
+ /**
+ * Type for private keys.
+ */
PRIVATE
}
}
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStore.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStore.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStore.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStore.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
package java.security;
import java.io.File;
@@ -43,6 +38,17 @@
import org.apache.harmony.security.internal.nls.Messages;
+/**
+ * {@code KeyStore} is responsible for maintaining cryptographic keys and their
+ * owners.
+ * <p>
+ * The type of the system key store can be changed by setting the {@code
+ * 'keystore.type'} property in the file named {@code
+ * JAVA_HOME/lib/security/java.security}.
+ *
+ * @see Certificate
+ * @see PrivateKey
+ */
public class KeyStore {
// Store KeyStore SERVICE name
@@ -72,6 +78,16 @@
// Store used type
private final String type;
+ /**
+ * Constructs a new instance of {@code KeyStore} with the given arguments.
+ *
+ * @param keyStoreSpi
+ * the concrete key store.
+ * @param provider
+ * the provider.
+ * @param type
+ * the type of the {@code KeyStore} to be constructed.
+ */
protected KeyStore(KeyStoreSpi keyStoreSpi, Provider provider, String type) {
this.type = type;
this.provider = provider;
@@ -80,7 +96,17 @@
}
/**
- * @throws NullPointerException if type is null
+ * Returns a new instance of {@code KeyStore} with the specified type.
+ *
+ * @param type
+ * the type of the returned {@code KeyStore}.
+ * @return a new instance of {@code KeyStore} with the specified type.
+ * @throws KeyStoreException
+ * if an error occurred during the creation of the new {@code
+ * KeyStore}.
+ * @throws NullPointerException
+ * if {@code type} is {@code null}.
+ * @see #getDefaultType
*/
public static KeyStore getInstance(String type) throws KeyStoreException {
if (type == null) {
@@ -97,10 +123,26 @@
}
/**
- *
- *
- * @throws NullPointerException if type is null (instead of
- * NoSuchAlgorithmException) as in 1.4 release
+ * Returns a new instance of {@code KeyStore} from the specified provider
+ * with the given type.
+ *
+ * @param type
+ * the type of the returned {@code KeyStore}.
+ * @param provider
+ * name of the provider of the {@code KeyStore}.
+ * @return a new instance of {@code KeyStore} from the specified provider
+ * with the given type.
+ * @throws KeyStoreException
+ * if an error occurred during the creation of the new {@code
+ * KeyStore}.
+ * @throws NoSuchProviderException
+ * if the specified provider is not available.
+ * @throws IllegalArgumentException
+ * if {@code provider} is {@code null} or the empty string.
+ * @throws NullPointerException
+ * if {@code type} is {@code null} (instead of
+ * NoSuchAlgorithmException) as in 1.4 release
+ * @see #getDefaultType
*/
public static KeyStore getInstance(String type, String provider)
throws KeyStoreException, NoSuchProviderException {
@@ -119,10 +161,24 @@
}
/**
- *
- *
- * throws NullPointerException if type is null (instead of
- * NoSuchAlgorithmException) as in 1.4 release
+ * Returns a new instance of {@code KeyStore} from the specified provider
+ * with the given type.
+ *
+ * @param type
+ * the type of the returned {@code KeyStore}.
+ * @param provider
+ * the provider of the {@code KeyStore}.
+ * @return a new instance of {@code KeyStore} from the specified provider
+ * with the given type.
+ * @throws KeyStoreException
+ * if an error occurred during the creation of the new {@code
+ * KeyStore}.
+ * @throws IllegalArgumentException
+ * if {@code provider} is {@code null} or the empty string.
+ * @throws NullPointerException
+ * if {@code type} is {@code null} (instead of
+ * NoSuchAlgorithmException) as in 1.4 release
+ * @see #getDefaultType
*/
public static KeyStore getInstance(String type, Provider provider)
throws KeyStoreException {
@@ -146,8 +202,13 @@
}
/**
- *
- *
+ * Returns the default type for {@code KeyStore} instances.
+ * <p>
+ * The default is specified in the {@code 'keystore.type'} property in the
+ * file named {@code JAVA_HOME/lib/security/java.security}. If this property
+ * is not set, {@code "jks"} will be used.
+ *
+ * @return the default type for {@code KeyStore} instances
*/
public static final String getDefaultType() {
String dt = AccessController.doPrivileged(
@@ -161,24 +222,39 @@
}
/**
- *
- *
+ * Returns the provider associated with this {@code KeyStore}.
+ *
+ * @return the provider associated with this {@code KeyStore}.
*/
public final Provider getProvider() {
return provider;
}
/**
- *
- *
+ * Returns the type of this {@code KeyStore}.
+ *
+ * @return the type of this {@code KeyStore}.
*/
public final String getType() {
return type;
}
/**
- *
- *
+ * Returns the key with the given alias, using the password to recover the
+ * key from the store.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @param password
+ * the password used to recover the key.
+ * @return the key with the specified alias, or {@code null} if the
+ * specified alias is not bound to an entry.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws NoSuchAlgorithmException
+ * if the algorithm for recovering the key is not available.
+ * @throws UnrecoverableKeyException
+ * if the key can not be recovered.
*/
public final Key getKey(String alias, char[] password)
throws KeyStoreException, NoSuchAlgorithmException,
@@ -190,8 +266,14 @@
}
/**
- *
- *
+ * Returns the certificate chain for the entry with the given alias.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @return the certificate chain for the entry with the given alias, or
+ * {@code null} if the specified alias is not bound to an entry.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
*/
public final Certificate[] getCertificateChain(String alias)
throws KeyStoreException {
@@ -202,8 +284,14 @@
}
/**
- *
- *
+ * Returns the trusted certificate for the entry with the given alias.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @return the trusted certificate for the entry with the given alias, or
+ * {@code null} if the specified alias is not bound to an entry.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
*/
public final Certificate getCertificate(String alias)
throws KeyStoreException {
@@ -214,8 +302,14 @@
}
/**
- *
- *
+ * Returns the creation date of the entry with the given alias.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @return the creation date, or {@code null} if the specified alias is not
+ * bound to an entry.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
*/
public final Date getCreationDate(String alias) throws KeyStoreException {
if (!isInit) {
@@ -225,12 +319,25 @@
}
/**
- *
- *
- * 1.4.2 and 1.5 releases throw unspecified NullPointerException -
- * when alias is null IllegalArgumentException - when password is null
- * IllegalArgumentException - when key is instance of PrivateKey and chain
- * is null or empty
+ * Associates the given alias with the key, password and certificate chain.
+ * <p>
+ * If the specified alias already exists, it will be reassigned.
+ *
+ * @param alias
+ * the alias for the key.
+ * @param key
+ * the key.
+ * @param password
+ * the password.
+ * @param chain
+ * the certificate chain.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws IllegalArgumentException
+ * if {@code key} is a {@code PrivateKey} and {@code chain} does
+ * not contain any certificates.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
public final void setKeyEntry(String alias, Key key, char[] password,
Certificate[] chain) throws KeyStoreException {
@@ -248,8 +355,28 @@
}
/**
- *
- *
+ * Associates the given alias with a key and a certificate chain.
+ * <p>
+ * If the specified alias already exists, it will be reassigned.
+ * <p>
+ * If this {@code KeyStore} is of type {@code "jks"}, {@code key} must be
+ * encoded conform to the PKS#8 standard as an
+ * {@link javax.crypto.EncryptedPrivateKeyInfo}.
+ *
+ * @param alias
+ * the alias for the key.
+ * @param key
+ * the key in an encoded format.
+ * @param chain
+ * the certificate chain.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized or if {@code key}
+ * is null.
+ * @throws IllegalArgumentException
+ * if {@code key} is a {@code PrivateKey} and {@code chain}
+ * does.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
public final void setKeyEntry(String alias, byte[] key, Certificate[] chain)
throws KeyStoreException {
@@ -260,10 +387,20 @@
}
/**
- *
- *
- * 1.4.2 and 1.5 releases throw unspecified NullPointerException
- * when alias is null
+ * Associates the given alias with a certificate.
+ * <p>
+ * If the specified alias already exists, it will be reassigned.
+ *
+ * @param alias
+ * the alias for the certificate.
+ * @param cert
+ * the certificate.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized, or an existing
+ * alias is not associated to an entry containing a trusted
+ * certificate, or this method fails for any other reason.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
public final void setCertificateEntry(String alias, Certificate cert)
throws KeyStoreException {
@@ -274,9 +411,16 @@
}
/**
- *
- *
- * 1.4.2 and 1.5 releases throw NullPointerException when alias is null
+ * Deletes the entry identified with the given alias from this {@code
+ * KeyStore}.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized, or if the entry
+ * can not be deleted.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
public final void deleteEntry(String alias) throws KeyStoreException {
if (!isInit) {
@@ -289,7 +433,13 @@
}
/**
- *
+ * Returns an {@code Enumeration} over all alias names stored in this
+ * {@code KeyStore}.
+ *
+ * @return an {@code Enumeration} over all alias names stored in this
+ * {@code KeyStore}.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
*/
public final Enumeration<String> aliases() throws KeyStoreException {
if (!isInit) {
@@ -299,10 +449,15 @@
}
/**
- *
- *
- * 1.4.2 and 1.5 releases throw unspecified NullPointerException when
- * alias is null
+ * Indicates whether the given alias is present in this {@code KeyStore}.
+ *
+ * @param alias
+ * the alias of an entry.
+ * @return {@code true} if the alias exists, {@code false} otherwise.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
public final boolean containsAlias(String alias) throws KeyStoreException {
if (!isInit) {
@@ -315,8 +470,11 @@
}
/**
- *
- *
+ * Returns the number of entries stored in this {@code KeyStore}.
+ *
+ * @return the number of entries stored in this {@code KeyStore}.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
*/
public final int size() throws KeyStoreException {
if (!isInit) {
@@ -326,10 +484,16 @@
}
/**
- *
- *
- * jdk1.4.2 and 1.5 releases throw unspecified NullPointerException
- * when alias is null
+ * Indicates whether the specified alias is associated with either a
+ * {@link PrivateKeyEntry} or a {@link SecretKeyEntry}.
+ *
+ * @param alias
+ * the alias of an entry.
+ * @return {@code true} if the given alias is associated with a key entry.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
public final boolean isKeyEntry(String alias) throws KeyStoreException {
if (!isInit) {
@@ -342,10 +506,17 @@
}
/**
- *
- *
- * jdk1.4.2 and 1.5 releases throw unspecified NullPointerException
- * when alias is null
+ * Indicates whether the specified alias is associated with a
+ * {@link TrustedCertificateEntry}.
+ *
+ * @param alias
+ * the alias of an entry.
+ * @return {@code true} if the given alias is associated with a certificate
+ * entry.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
public final boolean isCertificateEntry(String alias)
throws KeyStoreException {
@@ -359,8 +530,15 @@
}
/**
- *
- *
+ * Returns the alias associated with the first entry whose certificate
+ * matches the specified certificate.
+ *
+ * @param cert
+ * the certificate to find the associated entry's alias for.
+ * @return the alias or {@code null} if no entry with the specified
+ * certificate can be found.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
*/
public final String getCertificateAlias(Certificate cert)
throws KeyStoreException {
@@ -371,9 +549,23 @@
}
/**
- *
- *
- * throws IOException when stream or password is null
+ * Writes this {@code KeyStore} to the specified {@code OutputStream}. The
+ * data written to the {@code OutputStream} is protected by the specified
+ * password.
+ *
+ * @param stream
+ * the {@code OutputStream} to write the store's data to.
+ * @param password
+ * the password to protect the data.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws IOException
+ * if a problem occurred while writing to the stream.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws CertificateException
+ * if an exception occurred while storing the certificates of
+ * this {@code KeyStore}.
*/
public final void store(OutputStream stream, char[] password)
throws KeyStoreException, IOException, NoSuchAlgorithmException,
@@ -387,8 +579,23 @@
}
/**
- *
- *
+ * Stores this {@code KeyStore} using the specified {@code
+ * LoadStoreParameter}.
+ *
+ * @param param
+ * the {@code LoadStoreParameter} that specifies how to store
+ * this {@code KeyStore}, maybe {@code null}.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws IOException
+ * if a problem occurred while writing to the stream.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws CertificateException
+ * if an exception occurred while storing the certificates of
+ * this {@code KeyStore}.
+ * @throws IllegalArgumentException
+ * if the given {@link LoadStoreParameter} is not recognized.
*/
public final void store(LoadStoreParameter param) throws KeyStoreException,
IOException, NoSuchAlgorithmException, CertificateException {
@@ -399,8 +606,24 @@
}
/**
- *
- *
+ * Initializes this {@code KeyStore} from the provided {@code InputStream}.
+ * Pass {@code null} as the {@code stream} argument to initialize an empty
+ * {@code KeyStore} or to initialize a {@code KeyStore} which does not rely
+ * on an {@code InputStream}. This {@code KeyStore} utilizes the given
+ * password to verify the stored data.
+ *
+ * @param stream
+ * the {@code InputStream} to load this {@code KeyStore}'s data
+ * from or {@code null}.
+ * @param password
+ * the password to verify the stored data, maybe {@code null}.
+ * @throws IOException
+ * if a problem occurred while reading from the stream.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws CertificateException
+ * if an exception occurred while loading the certificates of
+ * this {@code KeyStore}.
*/
public final void load(InputStream stream, char[] password)
throws IOException, NoSuchAlgorithmException, CertificateException {
@@ -409,8 +632,21 @@
}
/**
- *
- *
+ * Loads this {@code KeyStore} using the specified {@code
+ * LoadStoreParameter}.
+ *
+ * @param param
+ * the {@code LoadStoreParameter} that specifies how to load this
+ * {@code KeyStore}, maybe {@code null}.
+ * @throws IOException
+ * if a problem occurred while reading from the stream.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws CertificateException
+ * if an exception occurred while loading the certificates of
+ * this {@code KeyStore}.
+ * @throws IllegalArgumentException
+ * if the given {@link LoadStoreParameter} is not recognized.
*/
public final void load(LoadStoreParameter param) throws IOException,
NoSuchAlgorithmException, CertificateException {
@@ -419,8 +655,24 @@
}
/**
- *
- *
+ * Returns the {@code Entry} with the given alias, using the specified
+ * {@code ProtectionParameter}.
+ *
+ * @param alias
+ * the alias of the requested entry.
+ * @param param
+ * the {@code ProtectionParameter} used to protect the requested
+ * entry, maybe {@code null}.
+ * @return he {@code Entry} with the given alias, using the specified
+ * {@code ProtectionParameter}.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws UnrecoverableEntryException
+ * if the entry can not be recovered.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
public final Entry getEntry(String alias, ProtectionParameter param)
throws NoSuchAlgorithmException, UnrecoverableEntryException,
@@ -435,10 +687,23 @@
}
/**
- *
- *
- * 1.5 release throws unspecified NullPointerException when alias or
- * entry is null
+ * Stores the given {@code Entry} in this {@code KeyStore} and associates
+ * the entry with the given {@code alias}. The entry is protected by the
+ * specified {@code ProtectionParameter}.
+ * <p>
+ * If the specified alias already exists, it will be reassigned.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @param entry
+ * the entry to store.
+ * @param param
+ * the {@code ProtectionParameter} to protect the entry.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null} or {@code entry} is {@code
+ * null}.
*/
public final void setEntry(String alias, Entry entry,
ProtectionParameter param) throws KeyStoreException {
@@ -455,7 +720,17 @@
}
/**
- *
+ * Indicates whether the entry for the given alias is assignable to the
+ * provided {@code Class}.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @param entryClass
+ * the type of the entry.
+ * @return {@code true} if the {@code Entry} for the alias is assignable to
+ * the specified {@code entryClass}.
+ * @throws KeyStoreException
+ * if this {@code KeyStore} is not initialized.
*/
public final boolean entryInstanceOf(String alias,
Class<? extends KeyStore.Entry> entryClass)
@@ -474,34 +749,61 @@
}
/**
- *
- *
- *
+ * {@code Builder} is used to construct new instances of {@code KeyStore}.
*/
public abstract static class Builder {
/**
- *
- *
+ * Constructs a new instance of {@code Builder}.
*/
protected Builder() {
}
/**
- *
- *
+ * Returns the {@code KeyStore} created by this {@code Builder}.
+ *
+ * @return the {@code KeyStore} created by this {@code Builder}.
+ * @throws KeyStoreException
+ * if an error occurred during construction.
*/
public abstract KeyStore getKeyStore() throws KeyStoreException;
/**
- *
- *
+ * Returns the {@code ProtectionParameter} to be used when a {@code
+ * Entry} with the specified alias is requested. Before this method is
+ * invoked, {@link #getKeyStore()} must be called.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @return the {@code ProtectionParameter} to be used when a {@code
+ * Entry} with the specified alias is requested.
+ * @throws KeyStoreException
+ * if an error occurred during the lookup for the protection
+ * parameter.
+ * @throws IllegalStateException
+ * if {@link #getKeyStore()} is not called prior the
+ * invocation of this method.
+ * @throws NullPointerException
+ * if {@code alias} is {@code null}.
*/
- public abstract ProtectionParameter getProtectionParameter(String alise)
+ public abstract ProtectionParameter getProtectionParameter(String alias)
throws KeyStoreException;
/**
- *
- *
+ * Returns a new {@code Builder} that holds the given {@code KeyStore}
+ * and the given {@code ProtectionParameter}.
+ *
+ * @param keyStore
+ * the {@code KeyStore} to be held.
+ * @param protectionParameter
+ * the {@code ProtectionParameter} to be held.
+ * @return a new instance of {@code Builder} that holds the specified
+ * {@code KeyStore} and the specified {@code
+ * ProtectionParameter}.
+ * @throws NullPointerException
+ * if {@code keyStore} or {@code protectionParameter} is
+ * {@code null}.
+ * @throws IllegalArgumentException
+ * if the given {@code KeyStore} is not initialized.
*/
public static Builder newInstance(KeyStore keyStore,
ProtectionParameter protectionParameter) {
@@ -520,8 +822,34 @@
}
/**
- *
- *
+ * Returns a new {@code Builder} that creates a new {@code KeyStore}
+ * based on the provided arguments.
+ * <p>
+ * If {@code provider} is {@code null}, all installed providers are
+ * searched, otherwise the key store from the specified provider is
+ * used.
+ *
+ * @param type
+ * the type of the {@code KeyStore} to be constructed.
+ * @param provider
+ * the provider of the {@code KeyStore} to be constructed,
+ * maybe {@code null}.
+ * @param file
+ * the {@code File} that contains the data for the {@code
+ * KeyStore}.
+ * @param protectionParameter
+ * the {@code ProtectionParameter} used to protect the stored
+ * keys.
+ * @return a new {@code Builder} that creates a new {@code KeyStore}
+ * based on the provided arguments.
+ * @throws NullPointerException
+ * if {@code type, protectionParameter} or {@code file} is
+ * {@code null}.
+ * @throws IllegalArgumentException
+ * {@code protectionParameter} not an instance of either
+ * {@code PasswordProtection} or {@code
+ * CallbackHandlerProtection}, {@code file} is not a file or
+ * does not exist at all.
*/
public static Builder newInstance(String type, Provider provider,
File file, ProtectionParameter protectionParameter) {
@@ -554,8 +882,31 @@
}
/**
- *
- *
+ * Returns a new {@code Builder} that creates a new {@code KeyStore}
+ * based on the provided arguments.
+ * <p>
+ * If {@code provider} is {@code null}, all installed providers are
+ * searched, otherwise the key store from the specified provider is
+ * used.
+ *
+ * @param type
+ * the type of the {@code KeyStore} to be constructed.
+ * @param provider
+ * the provider of the {@code KeyStore} to be constructed,
+ * maybe {@code null}.
+ * @param protectionParameter
+ * the {@code ProtectionParameter} used to protect the stored
+ * keys.
+ * @return a new {@code Builder} that creates a new {@code KeyStore}
+ * based on the provided arguments.
+ * @throws NullPointerException
+ * if {@code type} or {@code protectionParameter} is {@code
+ * null}.
+ * @throws IllegalArgumentException
+ * {@code protectionParameter} not an instance of either
+ * {@code PasswordProtection} or {@code
+ * CallbackHandlerProtection}, {@code file} is not a file or
+ * does not exist at all.
*/
public static Builder newInstance(String type, Provider provider,
ProtectionParameter protectionParameter) {
@@ -747,9 +1098,8 @@
}
/**
- *
- *
- *
+ * {@code CallbackHandlerProtection} is a {@code ProtectionParameter} that
+ * encapsulates a {@link CallbackHandler}.
*/
public static class CallbackHandlerProtection implements
ProtectionParameter {
@@ -757,8 +1107,13 @@
private final CallbackHandler callbackHandler;
/**
- *
- *
+ * Constructs a new instance of {@code CallbackHandlerProtection} with
+ * the {@code CallbackHandler}.
+ *
+ * @param handler
+ * the {@code CallbackHandler}.
+ * @throws NullPointerException
+ * if {@code handler} is {@code null}.
*/
public CallbackHandlerProtection(CallbackHandler handler) {
if (handler == null) {
@@ -768,8 +1123,9 @@
}
/**
- *
- *
+ * Returns the {@code CallbackHandler}.
+ *
+ * @return the {@code CallbackHandler}.
*/
public CallbackHandler getCallbackHandler() {
return callbackHandler;
@@ -777,30 +1133,33 @@
}
/**
- *
- *
- *
+ * {@code Entry} is the common marker interface for a {@code KeyStore}
+ * entry.
*/
public static interface Entry {
}
/**
- *
- *
- *
+ * {@code LoadStoreParameter} represents a parameter that specifies how a
+ * {@code KeyStore} can be loaded and stored.
+ *
+ * @see KeyStore#load(LoadStoreParameter)
+ * @see KeyStore#store(LoadStoreParameter)
*/
public static interface LoadStoreParameter {
/**
- *
- *
+ * Returns the {@code ProtectionParameter} which is used to protect data
+ * in the {@code KeyStore}.
+ *
+ * @return the {@code ProtectionParameter} which is used to protect data
+ * in the {@code KeyStore}, maybe {@code null}.
*/
public ProtectionParameter getProtectionParameter();
}
/**
- *
- *
- *
+ * {@code PasswordProtection} is a {@code ProtectionParameter} that protects
+ * a {@code KeyStore} using a password.
*/
public static class PasswordProtection implements ProtectionParameter,
Destroyable {
@@ -811,8 +1170,12 @@
private boolean isDestroyed = false;
/**
- *
- *
+ * Constructs a new instance of {@code PasswordProtection} with a
+ * password. A copy of the password is stored in the new {@code
+ * PasswordProtection} object.
+ *
+ * @param password
+ * the password, maybe {@code null}.
*/
public PasswordProtection(char[] password) {
if (password != null) {
@@ -821,8 +1184,11 @@
}
/**
- *
- *
+ * Returns the password.
+ *
+ * @return the password.
+ * @throws IllegalStateException
+ * if the password has been destroyed.
*/
public synchronized char[] getPassword() {
if (isDestroyed) {
@@ -832,8 +1198,10 @@
}
/**
- *
- *
+ * Destroys / invalidates the password.
+ *
+ * @throws DestroyFailedException
+ * if the password could not be invalidated.
*/
public synchronized void destroy() throws DestroyFailedException {
isDestroyed = true;
@@ -844,8 +1212,10 @@
}
/**
- *
- *
+ * Indicates whether the password is invalidated.
+ *
+ * @return {@code true} if the password is invalidated, {@code false}
+ * otherwise.
*/
public synchronized boolean isDestroyed() {
return isDestroyed;
@@ -853,17 +1223,16 @@
}
/**
- *
- *
- *
+ * {@code ProtectionParameter} is a marker interface for protection
+ * parameters. A protection parameter is used to protect the content of a
+ * {@code KeyStore}.
*/
public static interface ProtectionParameter {
}
/**
- *
- *
- *
+ * {@code PrivateKeyEntry} represents a {@code KeyStore} entry that
+ * holds a private key.
*/
public static final class PrivateKeyEntry implements Entry {
// Store Certificate chain
@@ -873,8 +1242,21 @@
private PrivateKey privateKey;
/**
- *
- *
+ * Constructs a new instance of {@code PrivateKeyEntry} with the given
+ * {@code PrivateKey} and the provided certificate chain.
+ *
+ * @param privateKey
+ * the private key.
+ * @param chain
+ * the ordered certificate chain with the certificate
+ * corresponding to the private key at index 0.
+ * @throws NullPointerException
+ * if {@code privateKey} or {@code chain} is {@code null}.
+ * @throws IllegalArgumentException
+ * if {@code chain.length == 0}, the algorithm of the
+ * private key does not match the algorithm of the public
+ * key of the first certificate or the certificates are not
+ * all of the same type.
*/
public PrivateKeyEntry(PrivateKey privateKey, Certificate[] chain) {
if (privateKey == null) {
@@ -922,32 +1304,37 @@
}
/**
- *
- *
+ * Returns the private key.
+ *
+ * @return the private key.
*/
public PrivateKey getPrivateKey() {
return privateKey;
}
/**
- *
- *
+ * Returns the certificate chain.
+ *
+ * @return the certificate chain.
*/
public Certificate[] getCertificateChain() {
return chain.clone();
}
/**
- *
- *
+ * Returns the certificate corresponding to the private key.
+ *
+ * @return the certificate corresponding to the private key.
*/
public Certificate getCertificate() {
return chain[0];
}
/**
- *
- *
+ * Returns a string containing a concise, human-readable description of
+ * this {@code PrivateKeyEntry}.
+ *
+ * @return a printable representation for this {@code PrivateKeyEntry}.
*/
public String toString() {
StringBuffer sb = new StringBuffer(
@@ -963,9 +1350,8 @@
}
/**
- *
- *
- *
+ * {@code SecretKeyEntry} represents a {@code KeyStore} entry that
+ * holds a secret key.
*/
public static final class SecretKeyEntry implements Entry {
@@ -973,8 +1359,13 @@
private final SecretKey secretKey;
/**
- *
- *
+ * Constructs a new instance of {@code SecretKeyEntry} with the given
+ * {@code SecretKey}.
+ *
+ * @param secretKey
+ * the secret key.
+ * @throws NullPointerException
+ * if {@code secretKey} is {@code null}.
*/
public SecretKeyEntry(SecretKey secretKey) {
if (secretKey == null) {
@@ -984,16 +1375,20 @@
}
/**
- *
- *
+ * Returns the secret key.
+ *
+ * @return the secret key.
*/
public SecretKey getSecretKey() {
return secretKey;
}
/**
- *
- *
+ * Returns a string containing a concise, human-readable description of
+ * this {@code SecretKeyEntry}.
+ *
+ * @return a printable representation for this {@code
+ * SecretKeyEntry}.
*/
public String toString() {
StringBuffer sb = new StringBuffer("SecretKeyEntry: algorithm - "); //$NON-NLS-1$
@@ -1003,9 +1398,8 @@
}
/**
- *
- *
- *
+ * {@code TrustedCertificateEntry} represents a {@code KeyStore} entry that
+ * holds a trusted certificate.
*/
public static final class TrustedCertificateEntry implements Entry {
@@ -1013,8 +1407,13 @@
private final Certificate trustCertificate;
/**
- *
- *
+ * Constructs a new instance of {@code TrustedCertificateEntry} with the
+ * given {@code Certificate}.
+ *
+ * @param trustCertificate
+ * the trusted certificate.
+ * @throws NullPointerException
+ * if {@code trustCertificate} is {@code null}.
*/
public TrustedCertificateEntry(Certificate trustCertificate) {
if (trustCertificate == null) {
@@ -1024,16 +1423,20 @@
}
/**
- *
- *
+ * Returns the trusted certificate.
+ *
+ * @return the trusted certificate.
*/
public Certificate getTrustedCertificate() {
return trustCertificate;
}
/**
- *
- *
+ * Returns a string containing a concise, human-readable description of
+ * this {@code TrustedCertificateEntry}.
+ *
+ * @return a printable representation for this {@code
+ * TrustedCertificateEntry}.
*/
public String toString() {
return "Trusted certificate entry:\n" + trustCertificate; //$NON-NLS-1$
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreException.java Tue Apr 28 17:01:41 2009
@@ -15,46 +15,53 @@
* limitations under the License.
*/
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
package java.security;
/**
- * @com.intel.drl.spec_ref
+ * {@code KeyStoreException} is a general {@code KeyStore} exception.
*
+ * @see KeyStore
*/
public class KeyStoreException extends GeneralSecurityException {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = -1119353179322377262L;
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code KeyStoreException} with the
+ * given message.
+ *
+ * @param msg
+ * the detail message for this exception.
*/
public KeyStoreException(String msg) {
super(msg);
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code KeyStoreException}.
*/
public KeyStoreException() {
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code KeyStoreException} with the
+ * given message and the cause.
+ *
+ * @param message
+ * the detail message for this exception.
+ * @param cause
+ * the exception which is the cause for this exception.
*/
public KeyStoreException(String message, Throwable cause) {
super(message, cause);
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code KeyStoreException} with the
+ * cause.
+ *
+ * @param cause
+ * the exception which is the cause for this exception.
*/
public KeyStoreException(Throwable cause) {
super(cause);
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/KeyStoreSpi.java Tue Apr 28 17:01:41 2009
@@ -30,52 +30,272 @@
import org.apache.harmony.security.internal.nls.Messages;
+/**
+ * {@code KeyStoreSpi} is the Service Provider Interface (SPI) definition for
+ * {@link KeyStore}.
+ *
+ * @see KeyStore
+ */
public abstract class KeyStoreSpi {
+ /**
+ * Returns the key with the given alias, using the password to recover the
+ * key from the store.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @param password
+ * the password used to recover the key.
+ * @return the key with the specified alias, or {@code null} if the
+ * specified alias is not bound to an entry.
+ * @throws NoSuchAlgorithmException
+ * if the algorithm for recovering the key is not available.
+ * @throws UnrecoverableKeyException
+ * if the key can not be recovered.
+ */
public abstract Key engineGetKey(String alias, char[] password)
throws NoSuchAlgorithmException, UnrecoverableKeyException;
+ /**
+ * Returns the certificate chain for the entry with the given alias.
+ *
+ * @param alias
+ * the alias for the entry
+ * @return the certificate chain for the entry with the given alias, or
+ * {@code null} if the specified alias is not bound to an entry.
+ */
public abstract Certificate[] engineGetCertificateChain(String alias);
+ /**
+ * Returns the trusted certificate for the entry with the given alias.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @return the trusted certificate for the entry with the given alias, or
+ * {@code null} if the specified alias is not bound to an entry.
+ */
public abstract Certificate engineGetCertificate(String alias);
+ /**
+ * Returns the creation date of the entry with the given alias.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @return the creation date, or {@code null} if the specified alias is not
+ * bound to an entry.
+ */
public abstract Date engineGetCreationDate(String alias);
+ /**
+ * Associates the given alias with the key, password and certificate chain.
+ * <p>
+ * If the specified alias already exists, it will be reassigned.
+ *
+ * @param alias
+ * the alias for the key.
+ * @param key
+ * the key.
+ * @param password
+ * the password.
+ * @param chain
+ * the certificate chain.
+ * @throws KeyStoreException
+ * if the specified key can not be protected, or if this
+ * operation fails for another reason.
+ * @throws IllegalArgumentException
+ * if {@code key} is a {@code PrivateKey} and {@code chain} does
+ * not contain any certificates.
+ */
public abstract void engineSetKeyEntry(String alias, Key key,
char[] password, Certificate[] chain) throws KeyStoreException;
+ /**
+ * Associates the given alias with a key and a certificate chain.
+ * <p>
+ * If the specified alias already exists, it will be reassigned.
+ *
+ * @param alias
+ * the alias for the key.
+ * @param key
+ * the key in an encoded format.
+ * @param chain
+ * the certificate chain.
+ * @throws KeyStoreException
+ * if this operation fails.
+ * @throws IllegalArgumentException
+ * if {@code key} is a {@code PrivateKey} and {@code chain}
+ * does.
+ */
public abstract void engineSetKeyEntry(String alias, byte[] key,
Certificate[] chain) throws KeyStoreException;
+ /**
+ * Associates the given alias with a certificate.
+ * <p>
+ * If the specified alias already exists, it will be reassigned.
+ *
+ * @param alias
+ * the alias for the certificate.
+ * @param cert
+ * the certificate.
+ * @throws KeyStoreException
+ * if an existing alias is not associated to an entry containing
+ * a trusted certificate, or this method fails for any other
+ * reason.
+ */
public abstract void engineSetCertificateEntry(String alias,
Certificate cert) throws KeyStoreException;
+ /**
+ * Deletes the entry identified with the given alias from this {@code
+ * KeyStoreSpi}.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @throws KeyStoreException
+ * if the entry can not be deleted.
+ */
public abstract void engineDeleteEntry(String alias)
throws KeyStoreException;
+ /**
+ * Returns an {@code Enumeration} over all alias names stored in this
+ * {@code KeyStoreSpi}.
+ *
+ * @return an {@code Enumeration} over all alias names stored in this
+ * {@code KeyStoreSpi}.
+ */
public abstract Enumeration<String> engineAliases();
+ /**
+ * Indicates whether the given alias is present in this {@code KeyStoreSpi}.
+ *
+ * @param alias
+ * the alias of an entry.
+ * @return {@code true} if the alias exists, {@code false} otherwise.
+ */
public abstract boolean engineContainsAlias(String alias);
+ /**
+ * Returns the number of entries stored in this {@code KeyStoreSpi}.
+ *
+ * @return the number of entries stored in this {@code KeyStoreSpi}.
+ */
public abstract int engineSize();
+ /**
+ * Indicates whether the specified alias is associated with either a
+ * {@link KeyStore.PrivateKeyEntry} or a {@link KeyStore.SecretKeyEntry}.
+ *
+ * @param alias
+ * the alias of an entry.
+ * @return {@code true} if the given alias is associated with a key entry.
+ */
public abstract boolean engineIsKeyEntry(String alias);
+ /**
+ * Indicates whether the specified alias is associated with a
+ * {@link KeyStore.TrustedCertificateEntry}.
+ *
+ * @param alias
+ * the alias of an entry.
+ * @return {@code true} if the given alias is associated with a certificate
+ * entry.
+ */
public abstract boolean engineIsCertificateEntry(String alias);
+ /**
+ * Returns the alias associated with the first entry whose certificate
+ * matches the specified certificate.
+ *
+ * @param cert
+ * the certificate to find the associated entry's alias for.
+ * @return the alias or {@code null} if no entry with the specified
+ * certificate can be found.
+ */
public abstract String engineGetCertificateAlias(Certificate cert);
+ /**
+ * Writes this {@code KeyStoreSpi} to the specified {@code OutputStream}.
+ * The data written to the {@code OutputStream} is protected by the
+ * specified password.
+ *
+ * @param stream
+ * the {@code OutputStream} to write the store's data to.
+ * @param password
+ * the password to protect the data.
+ * @throws IOException
+ * if a problem occurred while writing to the stream.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws CertificateException
+ * if the an exception occurred while storing the certificates
+ * of this code {@code KeyStoreSpi}.
+ */
public abstract void engineStore(OutputStream stream, char[] password)
throws IOException, NoSuchAlgorithmException, CertificateException;
+ /**
+ * Stores this {@code KeyStoreSpi} using the specified {@code
+ * LoadStoreParameter}.
+ *
+ * @param param
+ * the {@code LoadStoreParameter} that specifies how to store
+ * this {@code KeyStoreSpi}, maybe {@code null}.
+ * @throws IOException
+ * if a problem occurred while writing to the stream.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws CertificateException
+ * if the an exception occurred while storing the certificates
+ * of this code {@code KeyStoreSpi}.
+ * @throws IllegalArgumentException
+ * if the given {@link KeyStore.LoadStoreParameter} is not
+ * recognized.
+ */
public void engineStore(KeyStore.LoadStoreParameter param)
throws IOException, NoSuchAlgorithmException, CertificateException {
throw new UnsupportedOperationException(Messages.getString("security.33")); //$NON-NLS-1$
}
+ /**
+ * Loads this {@code KeyStoreSpi} from the given {@code InputStream}.
+ * Utilizes the given password to verify the stored data.
+ *
+ * @param stream
+ * the {@code InputStream} to load this {@code KeyStoreSpi}'s
+ * data from.
+ * @param password
+ * the password to verify the stored data, maybe {@code null}.
+ * @throws IOException
+ * if a problem occurred while reading from the stream.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws CertificateException
+ * if the an exception occurred while loading the certificates
+ * of this code {@code KeyStoreSpi}.
+ */
public abstract void engineLoad(InputStream stream, char[] password)
throws IOException, NoSuchAlgorithmException, CertificateException;
+ /**
+ * Loads this {@code KeyStoreSpi} using the specified {@code
+ * LoadStoreParameter}.
+ *
+ * @param param
+ * the {@code LoadStoreParameter} that specifies how to load this
+ * {@code KeyStoreSpi}, maybe {@code null}.
+ * @throws IOException
+ * if a problem occurred while reading from the stream.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws CertificateException
+ * if the an exception occurred while loading the certificates
+ * of this code {@code KeyStoreSpi}.
+ * @throws IllegalArgumentException
+ * if the given {@link KeyStore.LoadStoreParameter} is not
+ * recognized.
+ */
public void engineLoad(KeyStore.LoadStoreParameter param)
throws IOException, NoSuchAlgorithmException, CertificateException {
if (param == null) {
@@ -106,6 +326,24 @@
Messages.getString("security.35")); //$NON-NLS-1$
}
+ /**
+ * Returns the {@code Entry} with the given alias, using the specified
+ * {@code ProtectionParameter}.
+ *
+ * @param alias
+ * the alias of the requested entry.
+ * @param protParam
+ * the {@code ProtectionParameter}, used to protect the requested
+ * entry, maybe {@code null}.
+ * @return he {@code Entry} with the given alias, using the specified
+ * {@code ProtectionParameter}.
+ * @throws NoSuchAlgorithmException
+ * if the required algorithm is not available.
+ * @throws UnrecoverableEntryException
+ * if the entry can not be recovered.
+ * @throws KeyStoreException
+ * if this operation fails
+ */
public KeyStore.Entry engineGetEntry(String alias,
KeyStore.ProtectionParameter protParam) throws KeyStoreException,
NoSuchAlgorithmException, UnrecoverableEntryException {
@@ -150,6 +388,22 @@
throw new NoSuchAlgorithmException(Messages.getString("security.38")); //$NON-NLS-1$
}
+ /**
+ * Stores the given {@code Entry} in this {@code KeyStoreSpi} and associates
+ * the entry with the given {@code alias}. The entry is protected by the
+ * specified {@code ProtectionParameter}.
+ * <p>
+ * If the specified alias already exists, it will be reassigned.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @param entry
+ * the entry to store.
+ * @param protParam
+ * the {@code ProtectionParameter} to protect the entry.
+ * @throws KeyStoreException
+ * if this operation fails.
+ */
public void engineSetEntry(String alias, KeyStore.Entry entry,
KeyStore.ProtectionParameter protParam) throws KeyStoreException {
if (entry == null) {
@@ -204,6 +458,17 @@
Messages.getString("security.3B", entry.toString())); //$NON-NLS-1$
}
+ /**
+ * Indicates whether the entry for the given alias is assignable to the
+ * provided {@code Class}.
+ *
+ * @param alias
+ * the alias for the entry.
+ * @param entryClass
+ * the type of the entry.
+ * @return {@code true} if the {@code Entry} for the alias is assignable to
+ * the specified {@code entryClass}.
+ */
public boolean engineEntryInstanceOf(String alias,
Class<? extends KeyStore.Entry> entryClass) {
if (!engineContainsAlias(alias)) {
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigest.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigest.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigest.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigest.java Tue Apr 28 17:01:41 2009
@@ -22,6 +22,13 @@
import org.apache.harmony.security.fortress.Engine;
import org.apache.harmony.security.internal.nls.Messages;
+/**
+ * {@code MessageDigest} is an engine class which is capable of generating one
+ * way hash values for arbitrary input, utilizing the algorithm it was
+ * initialized with.
+ *
+ * @see MessageDigestSpi
+ */
public abstract class MessageDigest extends MessageDigestSpi {
// The service name
@@ -37,16 +44,28 @@
private String algorithm;
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code MessageDigest} with the name of
+ * the algorithm to use.
*
+ * @param algorithm
+ * the name of algorithm to use
*/
protected MessageDigest(String algorithm) {
this.algorithm = algorithm;
}
/**
- * @com.intel.drl.spec_ref
+ * Returns a new instance of {@code MessageDigest} that utilizes the
+ * specified algorithm.
*
+ * @param algorithm
+ * the name of the algorithm to use
+ * @return a new instance of {@code MessageDigest} that utilizes the
+ * specified algorithm
+ * @throws NoSuchAlgorithmException
+ * if the specified algorithm is not available
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null}
*/
public static MessageDigest getInstance(String algorithm)
throws NoSuchAlgorithmException {
@@ -70,8 +89,21 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Returns a new instance of {@code MessageDigest} that utilizes the
+ * specified algorithm from the specified provider.
*
+ * @param algorithm
+ * the name of the algorithm to use
+ * @param provider
+ * the name of the provider
+ * @return a new instance of {@code MessageDigest} that utilizes the
+ * specified algorithm from the specified provider
+ * @throws NoSuchAlgorithmException
+ * if the specified algorithm is not available
+ * @throws NoSuchProviderException
+ * if the specified provider is not available
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null}
*/
public static MessageDigest getInstance(String algorithm, String provider)
throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -88,20 +120,19 @@
}
/**
- * 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.
- *
+ * Returns a new instance of {@code MessageDigest} that utilizes the
+ * specified algorithm from the specified provider.
*
* @param algorithm
- * java.lang.String Name of the algorithm desired
+ * the name of the algorithm to use
* @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
+ * the provider
+ * @return a new instance of {@code MessageDigest} that utilizes the
+ * specified algorithm from the specified provider
+ * @throws NoSuchAlgorithmException
+ * if the specified algorithm is not available
+ * @throws NullPointerException
+ * if {@code algorithm} is {@code null}
*/
public static MessageDigest getInstance(String algorithm, Provider provider)
throws NoSuchAlgorithmException {
@@ -129,19 +160,18 @@
}
/**
- * Puts the receiver back in an initial state, such that it is ready to
- * compute a new hash.
+ * Puts this {@code MessageDigest} back in an initial state, such that it is
+ * ready to compute a one way hash value.
*/
public void reset() {
engineReset();
}
/**
- * Includes the argument in the hash value computed by the receiver.
+ * Updates this {@code MessageDigest} using the given {@code byte}.
*
* @param arg0
- * byte the byte to feed to the hash algorithm
- *
+ * the {@code byte} to update this {@code MessageDigest} with
* @see #reset()
*/
public void update(byte arg0) {
@@ -149,8 +179,17 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Updates this {@code MessageDigest} using the given {@code byte[]}.
*
+ * @param input
+ * the {@code byte} array
+ * @param offset
+ * the index of the first byte in {@code input} to update from
+ * @param len
+ * the number of bytes in {@code input} to update from
+ * @throws IllegalArgumentException
+ * if {@code offset} or {@code len} are not valid in respect to
+ * {@code input}
*/
public void update(byte[] input, int offset, int len) {
if (input == null ||
@@ -165,8 +204,12 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Updates this {@code MessageDigest} using the given {@code byte[]}.
*
+ * @param input
+ * the {@code byte} array
+ * @throws NullPointerException
+ * if {@code input} is {@code null}
*/
public void update(byte[] input) {
if (input == null) {
@@ -176,11 +219,10 @@
}
/**
- * Computes and answers the final hash value that the receiver represents.
+ * Computes and returns the final hash value for this {@link MessageDigest}.
* After the digest is computed the receiver is reset.
*
- * @return the hash the receiver computed
- *
+ * @return the computed one way hash value
* @see #reset
*/
public byte[] digest() {
@@ -188,8 +230,22 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Computes and stores the final hash value for this {@link MessageDigest}.
+ * After the digest is computed the receiver is reset.
*
+ * @param buf
+ * the buffer to store the result
+ * @param offset
+ * the index of the first byte in {@code buf} to store
+ * @param len
+ * the number of bytes allocated for the digest
+ * @return the number of bytes written to {@code buf}
+ * @throws DigestException
+ * if an error occures
+ * @throws IllegalArgumentException
+ * if {@code offset} or {@code len} are not valid in respect to
+ * {@code buf}
+ * @see #reset()
*/
public int digest(byte[] buf, int offset, int len) throws DigestException {
if (buf == null ||
@@ -204,8 +260,14 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Performs the final update and then computes and returns the final hash
+ * value for this {@link MessageDigest}. After the digest is computed the
+ * receiver is reset.
+ *
+ * @param input
+ * the {@code byte} array
+ * @return the computed one way hash value
+ * @see #reset()
*/
public byte[] digest(byte[] input) {
update(input);
@@ -213,25 +275,24 @@
}
/**
- * Answers a string containing a concise, human-readable description of the
- * receiver.
+ * Returns a string containing a concise, human-readable description of this
+ * {@code MessageDigest} including the name of its algorithm.
*
- * @return a printable representation for the receiver.
+ * @return a printable representation for this {@code MessageDigest}
*/
public String toString() {
return "MESSAGE DIGEST " + algorithm; //$NON-NLS-1$
}
/**
- * Does a simply byte-per-byte compare of the two digests.
+ * Indicates whether to digest are equal by performing a simply
+ * byte-per-byte compare of the two digests.
*
* @param digesta
- * One of the digests to compare
+ * the first digest to be compared
* @param digestb
- * The digest to compare to
- *
- * @return <code>true</code> if the two hashes are equal
- * <code>false</code> if the two hashes are not equal
+ * the second digest to be compared
+ * @return {@code true} if the two hashes are equal, {@code false} otherwise
*/
public static boolean isEqual(byte[] digesta, byte[] digestb) {
if (digesta.length != digestb.length) {
@@ -246,29 +307,29 @@
}
/**
- * Answers the standard Java Security name for the algorithm being used by
- * the receiver.
+ * Returns the name of the algorithm of this {@code MessageDigest}.
*
- * @return String the name of the algorithm
+ * @return the name of the algorithm of this {@code MessageDigest}
*/
public final String getAlgorithm() {
return algorithm;
}
/**
- * Returns the Provider of the digest represented by the receiver.
+ * Returns the provider associated with this {@code MessageDigest}.
*
- * @return Provider an instance of a subclass of java.security.Provider
+ * @return the provider associated with this {@code MessageDigest}
*/
public final Provider getProvider() {
return provider;
}
/**
- * Return the engine digest length in bytes. Default is 0.
- *
- * @return int the engine digest length in bytes
+ * Returns the engine digest length in bytes. If the implementation does not
+ * implement this function or is not an instance of {@code Cloneable},
+ * {@code 0} is returned.
*
+ * @return the digest length in bytes, or {@code 0}
*/
public final int getDigestLength() {
int l = engineGetDigestLength();
@@ -286,10 +347,6 @@
}
}
- /**
- * @com.intel.drl.spec_ref
- *
- */
public Object clone() throws CloneNotSupportedException {
if (this instanceof Cloneable) {
return super.clone();
@@ -299,8 +356,10 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Updates this {@code MessageDigest} using the given {@code input}.
*
+ * @param input
+ * the {@code ByteBuffer}
*/
public final void update(ByteBuffer input) {
engineUpdate(input);
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigestSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigestSpi.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigestSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/MessageDigestSpi.java Tue Apr 28 17:01:41 2009
@@ -15,11 +15,6 @@
* limitations under the License.
*/
-/**
-* @author Boris V. Kuznetsov
-* @version $Revision$
-*/
-
package java.security;
import java.nio.ByteBuffer;
@@ -28,39 +23,54 @@
/**
- * 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.
+ * {@code MessageDigestSpi} is the Service Provider Interface (SPI) definition
+ * for {@link MessageDigest}. Examples of digest algorithms are MD5 and SHA. A
+ * digest is a secure one way hash function for a stream of bytes. It acts like
+ * a fingerprint for a stream of bytes.
*
+ * @see MessageDigest
*/
public abstract class MessageDigestSpi {
/**
- * @com.intel.drl.spec_ref
+ * Returns the engine digest length in bytes. If the implementation does not
+ * implement this function {@code 0} is returned.
*
+ * @return the digest length in bytes, or {@code 0}.
*/
protected int engineGetDigestLength() {
return 0;
}
/**
- * @com.intel.drl.spec_ref
+ * Updates this {@code MessageDigestSpi} using the given {@code byte}.
*
+ * @param input
+ * the {@code byte} to update this {@code MessageDigestSpi} with.
+ * @see #engineReset()
*/
protected abstract void engineUpdate(byte input);
/**
- * @com.intel.drl.spec_ref
+ * Updates this {@code MessageDigestSpi} using the given {@code byte[]}.
*
+ * @param input
+ * the {@code byte} array.
+ * @param offset
+ * the index of the first byte in {@code input} to update from.
+ * @param len
+ * the number of bytes in {@code input} to update from.
+ * @throws IllegalArgumentException
+ * if {@code offset} or {@code len} are not valid in respect to
+ * {@code input}.
*/
protected abstract void engineUpdate(byte[] input, int offset, int len);
/**
- * @com.intel.drl.spec_ref
+ * Updates this {@code MessageDigestSpi} using the given {@code input}.
*
+ * @param input
+ * the {@code ByteBuffer}.
*/
protected void engineUpdate(ByteBuffer input) {
if (!input.hasRemaining()) {
@@ -82,14 +92,33 @@
}
/**
- * @com.intel.drl.spec_ref
+ * Computes and returns the final hash value for this
+ * {@link MessageDigestSpi}. After the digest is computed the receiver is
+ * reset.
*
+ * @return the computed one way hash value.
+ * @see #engineReset()
*/
protected abstract byte[] engineDigest();
/**
- * @com.intel.drl.spec_ref
- *
+ * Computes and stores the final hash value for this
+ * {@link MessageDigestSpi}. After the digest is computed the receiver is
+ * reset.
+ *
+ * @param buf
+ * the buffer to store the result in.
+ * @param offset
+ * the index of the first byte in {@code buf} to store in.
+ * @param len
+ * the number of bytes allocated for the digest.
+ * @return the number of bytes written to {@code buf}.
+ * @throws DigestException
+ * if an error occures.
+ * @throws IllegalArgumentException
+ * if {@code offset} or {@code len} are not valid in respect to
+ * {@code buf}.
+ * @see #engineReset()
*/
protected int engineDigest(byte[] buf, int offset, int len)
throws DigestException {
@@ -114,15 +143,11 @@
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Puts this {@code MessageDigestSpi} back in an initial state, such that it
+ * is ready to compute a one way hash value.
*/
protected abstract void engineReset();
- /**
- * @com.intel.drl.spec_ref
- *
- */
public Object clone() throws CloneNotSupportedException {
return super.clone();
}
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchAlgorithmException.java Tue Apr 28 17:01:41 2009
@@ -15,54 +15,52 @@
* limitations under the License.
*/
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
package java.security;
/**
- * Instances of this class are thrown when an attempt is made to access an
- * algorithm which is not provided by the library.
- *
- * @see Throwable
+ * {@code NoSuchAlgorithmException} indicates that a requested algorithm could
+ * not be found.
*/
public class NoSuchAlgorithmException extends GeneralSecurityException {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = -7443947487218346562L;
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- *
- * @param msg
- * String The detail message for the exception.
- */
+ /**
+ * Constructs a new instance of {@code NoSuchAlgorithmException} with the
+ * given message.
+ *
+ * @param msg
+ * the detail message for this exception.
+ */
public NoSuchAlgorithmException(String msg) {
super(msg);
}
- /**
- * Constructs a new instance of this class with its walkback filled in.
- *
- */
+ /**
+ * Constructs a new instance of {@code NoSuchAlgorithmException}.
+ */
public NoSuchAlgorithmException() {
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code NoSuchAlgorithmException} with the
+ * given message and the cause.
+ *
+ * @param message
+ * the detail message for this exception.
+ * @param cause
+ * the exception which is the cause for this exception.
*/
public NoSuchAlgorithmException(String message, Throwable cause) {
super(message, cause);
}
/**
- * @com.intel.drl.spec_ref
+ * Constructs a new instance of {@code NoSuchAlgorithmException} with the
+ * cause.
+ *
+ * @param cause
+ * the exception which is the cause for this exception.
*/
public NoSuchAlgorithmException(Throwable cause) {
super(cause);
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchProviderException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchProviderException.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchProviderException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/NoSuchProviderException.java Tue Apr 28 17:01:41 2009
@@ -15,41 +15,30 @@
* limitations under the License.
*/
-/**
-* @author Vera Y. Petrashkova
-* @version $Revision$
-*/
-
package java.security;
/**
- * Instances of this class are thrown when an attempt is made to access a
- * provider by name which is not currently available.
- *
- *
- * @see Throwable
+ * {@code NoSuchProviderException} indicates that a requested security provider
+ * could not be found.
*/
public class NoSuchProviderException extends GeneralSecurityException {
- /**
- * @com.intel.drl.spec_ref
- */
+
private static final long serialVersionUID = 8488111756688534474L;
- /**
- * Constructs a new instance of this class with its walkback and message
- * filled in.
- *
- * @param msg
- * String The detail message for the exception.
- */
+ /**
+ * Constructs a new instance of {@code NoSuchProviderException} with the
+ * given message.
+ *
+ * @param msg
+ * the detail message for this exception.
+ */
public NoSuchProviderException(String msg) {
super(msg);
}
- /**
- * Constructs a new instance of this class with its walkback filled in.
- *
- */
+ /**
+ * Constructs a new instance of {@code NoSuchProviderException}.
+ */
public NoSuchProviderException() {
}
}
Modified: harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permission.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permission.java?rev=769463&r1=769462&r2=769463&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permission.java (original)
+++ harmony/enhanced/classlib/trunk/modules/security/src/main/java/common/java/security/Permission.java Tue Apr 28 17:01:41 2009
@@ -15,91 +15,111 @@
* limitations under the License.
*/
-/**
-* @author Alexey V. Varlamov
-* @version $Revision$
-*/
-
package java.security;
import java.io.Serializable;
/**
- * Abstract superclass of all classes which represent permission to access
- * system resources.
- *
+ * {@code Permission} is the common base class of all permissions that
+ * participate in the access control security framework around
+ * {@link AccessController} and {@link AccessControlContext}. A permission
+ * constitutes of a name and associated actions.
*/
public abstract class Permission implements Guard, Serializable {
- /**
- * @com.intel.drl.spec_ref
- */
private static final long serialVersionUID = -5636570222231596674L;
private final String name;
- /**
- * @com.intel.drl.spec_ref
+ /**
+ * Compares the specified object with this {@code Permission} for equality
+ * and returns {@code true} if the specified object is equal, {@code false}
+ * otherwise.
+ * <p>
+ * The {@link #implies(Permission)} method should be used for making access
+ * control checks.
+ *
+ * @param obj
+ * object to be compared for equality with this {@code
+ * Permission}.
+ * @return {@code true} if the specified object is equal to this {@code
+ * Permission}, otherwise {@code false}.
*/
public abstract boolean equals(Object obj);
- /**
- * Answers an integer hash code for the receiver. Any two objects which
- * answer <code>true</code> when passed to <code>.equals</code> must
- * answer the same value for this method.
- *
- *
- * @return int the receiver's hash.
- *
- * @see #equals
- */
+ /**
+ * Returns the hash code value for this {@code Permission}. Returns the same
+ * hash code for {@code Permission}s that are equal to each other as
+ * required by the general contract of {@link Object#hashCode}.
+ *
+ * @return the hash code value for this {@code Permission}.
+ * @see Object#equals(Object)
+ * @see Permission#equals(Object)
+ */
public abstract int hashCode();
- /**
- * 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.
- */
+ /**
+ * Returns a comma separated string identifying the actions associated with
+ * this permission. The returned actions are in canonical form. For example:
+ *
+ * <pre>
+ * sp0 = new SocketPermission("www.example.com", "connect,resolve")
+ * sp1 = new SocketPermission("www.example.com", "resolve,connect")
+ * sp0.getActions().equals(sp1.getActions()) //yields true
+ * </pre>
+ *
+ * Both permissions return "connect,resolve" (in that order) if {@code
+ * #getActions()} is invoked. Returns an empty String, if no actions are
+ * associated with this permission.
+ *
+ * @return the actions associated with this permission or an empty string if
+ * no actions are associated with this permission.
+ */
public abstract String getActions();
- /**
- * Indicates whether the argument permission is implied by the receiver.
- *
- *
- * @return boolean <code>true</code> if the argument permission is implied
- * by the receiver, and <code>false</code> if it is not.
- * @param permission
- * Permission the permission to check.
- */
+ /**
+ * Indicates whether the specified permission is implied by this permission.
+ * The {@link AccessController} uses this method to check whether permission
+ * protected access is allowed with the present policy.
+ *
+ * @param permission
+ * the permission to check against this permission.
+ * @return {@code true} if the specified permission is implied by this
+ * permission, {@code false} otherwise.
+ */
public abstract boolean implies(Permission permission);
- /**
- * Constructs a new instance of this class with its name set to the
- * argument.
- *
- *
- * @param name
- * String the name of the permission.
- */
+ /**
+ * Constructs a new instance of {@code Permission} with its name.
+ *
+ * @param name
+ * the name of the permission.
+ */
public Permission(String name) {
this.name = name;
}
- /**
- * Answers the name of the receiver.
- *
- *
- * @return String the receiver's name.
- */
+ /**
+ * Returns the name of this permission.
+ *
+ * @return the name of this permission.
+ */
public final String getName() {
return name;
}
- /**
- * @com.intel.drl.spec_ref
+ /**
+ * Invokes {@link SecurityManager#checkPermission(Permission)} with this
+ * permission as its argument. This method implements the {@link Guard}
+ * interface.
+ *
+ * @param obj
+ * as specified in {@link Guard#checkGuard(Object)} but ignored
+ * in this implementation.
+ * @throws SecurityException
+ * if this permission is not granted.
+ * @see Guard
+ * @see SecurityManager#checkPermission(Permission)
*/
public void checkGuard(Object obj) throws SecurityException {
SecurityManager sm = System.getSecurityManager();
@@ -108,25 +128,27 @@
}
}
- /**
- * 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.
- */
+ /**
+ * Returns a specific {@link PermissionCollection} container for permissions
+ * of this type. Returns {@code null} if any permission collection can be
+ * used.
+ * <p>
+ * Subclasses may override this method to return an appropriate collection
+ * for the specific permissions they implement.
+ *
+ * @return an empty {@link PermissionCollection} or {@code null} if any
+ * permission collection can be used.
+ */
public PermissionCollection newPermissionCollection() {
return null;
}
- /**
- * Answers a string containing a concise, human-readable description of the
- * receiver.
- *
- *
- * @return String a printable representation for the receiver.
- */
+ /**
+ * Returns a string containing a concise, human-readable description of the
+ * this {@code Permission} including its name and its actions.
+ *
+ * @return a printable representation for this {@code Permission}.
+ */
public String toString() {
String actions = getActions();
actions = (actions == null || actions.length() == 0) ? "" : " " //$NON-NLS-1$ //$NON-NLS-2$