harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [5/18] - in /harmony/enhanced/classlib/branches/java6: ./ modules/annotation/src/main/java/java/lang/annotation/ modules/archive/src/main/java/java/util/jar/ modules/archive/src/main/java/java/util/zip/ modules/auth/src/main/java/co...
Date Sun, 26 Apr 2009 12:30:06 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanism.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanism.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanism.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanism.java Sun Apr 26 12:30:01 2009
@@ -31,6 +31,10 @@
 import org.apache.harmony.crypto.internal.nls.Messages;
 import org.apache.harmony.security.fortress.Engine;
 
+/**
+ * This class implements the functionality of an exemption mechanism such as
+ * <i>key recovery</i>, <i>key weakening</i>, or <i>key escrow</i>.
+ */
 public class ExemptionMechanism {
 
     // Used to access common engine functionality
@@ -54,6 +58,16 @@
     // Indicates if blob generated successfully
     private boolean generated;
 
+    /**
+     * Creates a {@code ExemptionMechanism} instance.
+     *
+     * @param exmechSpi
+     *            the implementation delegate.
+     * @param provider
+     *            the associated provider.
+     * @param mechanism
+     *            the name of the mechanism.
+     */
     protected ExemptionMechanism(ExemptionMechanismSpi exmechSpi,
             Provider provider, String mechanism) {
         this.mechanism = mechanism;
@@ -62,10 +76,27 @@
         isInit = false;
     }
 
+    /**
+     * Returns the name of this {@code ExemptionMechanism}.
+     *
+     * @return the name of this {@code ExemptionMechanism}.
+     */
     public final String getName() {
         return mechanism;
     }
 
+    /**
+     * Returns a new {@code ExemptionMechanism} instance that provides the
+     * specified exemption mechanism algorithm.
+     *
+     * @param algorithm
+     *            the name of the requested exemption mechanism.
+     * @return the new {@code ExemptionMechanism} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available by any provider.
+     * @throws NullPointerException
+     *             if the algorithm parameter is {@code null}.
+     */
     public static final ExemptionMechanism getInstance(String algorithm)
             throws NoSuchAlgorithmException {
         if (algorithm == null) {
@@ -78,6 +109,25 @@
         }
     }
 
+    /**
+     * Returns a new {@code ExemptionMechansm} instance that provides the
+     * specified exemption mechanism algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the requested exemption mechanism.
+     * @param provider
+     *            the name of the provider that is providing the algorithm.
+     * @return the new {@code ExemptionMechanism} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not provided by the specified
+     *             provider.
+     * @throws NoSuchProviderException
+     *             if the specified provider is not available.
+     * @throws NullPointerException
+     *             if the algorithm parameter is {@code null}.
+     * @throws IllegalArgumentException
+     *             if the provider parameter is {@code null}.
+     */
     public static final ExemptionMechanism getInstance(String algorithm,
             String provider) throws NoSuchAlgorithmException,
             NoSuchProviderException {
@@ -94,6 +144,23 @@
         return getInstance(algorithm, impProvider);
     }
 
+    /**
+     * Returns a new {@code ExemptionMechanism} instance that provides the
+     * specified exemption mechanism algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the requested exemption mechanism.
+     * @param provider
+     *            the provider that is providing the algorithm.
+     * @return the new {@code ExemptionMechanism} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not provided by the specified
+     *             provider.
+     * @throws NullPointerException
+     *             if the algorithm parameter is {@code null}.
+     * @throws IllegalArgumentException
+     *             if the provider parameter is {@code null}.
+     */
     public static final ExemptionMechanism getInstance(String algorithm,
             Provider provider) throws NoSuchAlgorithmException {
         if (algorithm == null) {
@@ -109,10 +176,28 @@
         }
     }
 
+    /**
+     * Returns the provider of this {@code ExemptionMechanism} instance.
+     *
+     * @return the provider of this {@code ExemptionMechanism} instance.
+     */
     public final Provider getProvider() {
         return provider;
     }
 
+    /**
+     * Returns whether the result blob for this {@code ExemptionMechanism}
+     * instance has been generated successfully and that the specified key is
+     * the same as the one that was used to initialize and generate.
+     *
+     * @param key
+     *            the key to verify.
+     * @return whether the result blob for this {@code ExemptionMechanism}
+     *         instance has been generated successfully.
+     * @throws ExemptionMechanismException
+     *             if an error occurs while determining whether the result blob
+     *             has been generated successfully.
+     */
     public final boolean isCryptoAllowed(Key key)
             throws ExemptionMechanismException {
 
@@ -124,6 +209,18 @@
         return false;
     }
 
+    /**
+     * Returns the size in bytes for the output buffer needed to hold the output
+     * of the next {@link #genExemptionBlob} call, given the specified {@code
+     * inputLen} (in bytes).
+     *
+     * @param inputLen
+     *            the specified input length (in bytes).
+     * @return the size in bytes for the output buffer.
+     * @throws IllegalStateException
+     *             if this {@code ExemptionMechanism} instance is not
+     *             initialized.
+     */
     public final int getOutputSize(int inputLen) throws IllegalStateException {
         if (!isInit) {
             throw new IllegalStateException(Messages.getString("crypto.2D"));
@@ -131,6 +228,17 @@
         return spiImpl.engineGetOutputSize(inputLen);
     }
 
+    /**
+     * Initializes this {@code ExemptionMechanism} instance with the
+     * specified key.
+     *
+     * @param key
+     *            the key to initialize this instance with.
+     * @throws InvalidKeyException
+     *             if the key cannot be used to initialize this mechanism.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during initialization.
+     */
     public final void init(Key key) throws InvalidKeyException,
             ExemptionMechanismException {
         generated = false;
@@ -139,6 +247,22 @@
         isInit = true;
     }
 
+    /**
+     * Initializes this {@code ExemptionMechanism} instance with the
+     * specified key and algorithm parameters.
+     *
+     * @param key
+     *            the key to initialize this instance with.
+     * @param param
+     *            the parameters for this exemption mechanism algorithm.
+     * @throws InvalidKeyException
+     *             if the key cannot be used to initialize this mechanism.
+     * @throws InvalidAlgorithmParameterException
+     *             if the parameters cannot be used to initialize this
+     *             mechanism.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during initialization.
+     */
     public final void init(Key key, AlgorithmParameters param)
             throws InvalidKeyException, InvalidAlgorithmParameterException,
             ExemptionMechanismException {
@@ -148,6 +272,22 @@
         isInit = true;
     }
 
+    /**
+     * Initializes this {@code ExemptionMechanism} instance with the
+     * specified key and algorithm parameters.
+     *
+     * @param key
+     *            the key to initialize this instance with.
+     * @param param
+     *            the parameters for this exemption mechanism algorithm.
+     * @throws InvalidKeyException
+     *             if the key cannot be used to initialize this mechanism.
+     * @throws InvalidAlgorithmParameterException
+     *             the the parameters cannot be used to initialize this
+     *             mechanism.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during initialization.
+     */
     public final void init(Key key, AlgorithmParameterSpec param)
             throws InvalidKeyException, InvalidAlgorithmParameterException,
             ExemptionMechanismException {
@@ -157,6 +297,16 @@
         isInit = true;
     }
 
+    /**
+     * Generates the result key blob for this exemption mechanism.
+     *
+     * @return the result key blob for this exemption mechanism.
+     * @throws IllegalStateException
+     *             if this {@code ExemptionMechanism} instance is not
+     *             initialized.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during generation.
+     */
     public final byte[] genExemptionBlob() throws IllegalStateException,
             ExemptionMechanismException {
         if (!isInit) {
@@ -168,12 +318,44 @@
         return result;
     }
 
+    /**
+     * Generates the result key blob for this exemption mechanism and stores it
+     * into the {@code output} buffer.
+     *
+     * @param output
+     *            the output buffer for the result key blob.
+     * @return the number of bytes written to the {@code output} buffer.
+     * @throws IllegalStateException
+     *             if this {@code ExemptionMechanism} instance is not
+     *             initialized.
+     * @throws ShortBufferException
+     *             if the provided buffer is too small for the result key blob.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during generation.
+     */
     public final int genExemptionBlob(byte[] output)
             throws IllegalStateException, ShortBufferException,
             ExemptionMechanismException {
         return genExemptionBlob(output, 0);
     }
 
+    /**
+     * Generates the result key blob for this exemption mechanism and stores it
+     * into the {@code output} buffer at offset {@code outputOffset}.
+     *
+     * @param output
+     *            the output buffer for the result key blob.
+     * @param outputOffset
+     *            the offset in the output buffer to start.
+     * @return the number of bytes written to the {@code output} buffer.
+     * @throws IllegalStateException
+     *             if this {@code ExemptionMechanism} instance is not
+     *             initialized.
+     * @throws ShortBufferException
+     *             if the provided buffer is too small for the result key blob.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during generation.
+     */
     public final int genExemptionBlob(byte[] output, int outputOffset)
             throws IllegalStateException, ShortBufferException,
             ExemptionMechanismException {
@@ -186,6 +368,9 @@
         return len;
     }
 
+    /**
+     * Frees the references to the key used to initialize this instance.
+     */
     @Override
     protected void finalize() {
         initKey = null;

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismException.java Sun Apr 26 12:30:01 2009
@@ -25,8 +25,7 @@
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This is the base class for {@code ExemptionMechanismException}.
  */
 public class ExemptionMechanismException extends GeneralSecurityException {
 
@@ -36,16 +35,18 @@
     private static final long serialVersionUID = 1572699429277957109L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code ExemptionMechanismException} with the specified
+     * message.
      * 
+     * @param msg
+     *            the exception message.
      */
     public ExemptionMechanismException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Creates a new {@code ExemptionMechanismException} with no message.
      */
     public ExemptionMechanismException() {
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismSpi.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismSpi.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismSpi.java Sun Apr 26 12:30:01 2009
@@ -29,56 +29,105 @@
 import java.security.spec.AlgorithmParameterSpec;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The <i>Service Provider Interface</i> (<b>SPI</b>) definition for the {@code
+ * ExemptionMechanism} class.
  */
 public abstract class ExemptionMechanismSpi {
+
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code ExemptionMechanismSpi} instance.
      */
     public ExemptionMechanismSpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates the result key blob for this exemption mechanism.
+     *
+     * @return the result key blob for this exemption mechanism.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during generation.
      */
     protected abstract byte[] engineGenExemptionBlob()
             throws ExemptionMechanismException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates the result key blob for this exemption mechanism and stores it
+     * into the {@code output} buffer at offset {@code outputOffset}.
+     *
+     * @param output
+     *            the output buffer for the result key blob.
+     * @param outputOffset
+     *            the offset in the output buffer to start.
+     * @return the number of bytes written to the {@code output} buffer.
+     * @throws ShortBufferException
+     *             if the provided buffer is too small for the result key blob.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during generation.
      */
     protected abstract int engineGenExemptionBlob(byte[] output,
             int outputOffset) throws ShortBufferException,
             ExemptionMechanismException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the size in bytes for the output buffer needed to hold the output
+     * of the next {@link #engineGenExemptionBlob} call, given the specified
+     * {@code inputLen} (in bytes).
+     *
+     * @param inputLen
+     *            the specified input length (in bytes).
+     * @return the size in bytes for the output buffer.
      */
     protected abstract int engineGetOutputSize(int inputLen);
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code ExemptionMechanism} instance with the specified
+     * key.
+     *
+     * @param key
+     *            the key to initialize this instance with.
+     * @throws InvalidKeyException
+     *             if the key cannot be used to initialize this mechanism.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during initialization.
      */
     protected abstract void engineInit(Key key) throws InvalidKeyException,
             ExemptionMechanismException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code ExemptionMechanism} instance with the specified
+     * key and algorithm parameters.
+     *
+     * @param key
+     *            the key to initialize this instance with.
+     * @param params
+     *            the parameters for this exemption mechanism algorithm.
+     * @throws InvalidKeyException
+     *             if the key cannot be used to initialize this mechanism.
+     * @throws InvalidAlgorithmParameterException
+     *             if the parameters cannot be used to initialize this
+     *             mechanism.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during initialization.
      */
     protected abstract void engineInit(Key key, AlgorithmParameters params)
             throws InvalidKeyException, InvalidAlgorithmParameterException,
             ExemptionMechanismException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code ExemptionMechanism} instance with the specified
+     * key and algorithm parameters.
+     *
+     * @param key
+     *            the key to initialize this instance with.
+     * @param params
+     *            the parameters for this exemption mechanism algorithm.
+     * @throws InvalidKeyException
+     *             if the key cannot be used to initialize this mechanism.
+     * @throws InvalidAlgorithmParameterException
+     *             the the parameters cannot be used to initialize this
+     *             mechanism.
+     * @throws ExemptionMechanismException
+     *             if error(s) occur during initialization.
      */
     protected abstract void engineInit(Key key, AlgorithmParameterSpec params)
             throws InvalidKeyException, InvalidAlgorithmParameterException,

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/IllegalBlockSizeException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/IllegalBlockSizeException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/IllegalBlockSizeException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/IllegalBlockSizeException.java Sun Apr 26 12:30:01 2009
@@ -25,8 +25,8 @@
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception, that is thrown when the data length provided to a block cipher
+ * does not match the block size of the cipher.
  */
 public class IllegalBlockSizeException extends GeneralSecurityException {
 
@@ -36,16 +36,18 @@
     private static final long serialVersionUID = -1965144811953540392L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code IllegalBlockSizeException} with the specified
+     * message.
      * 
+     * @param msg
+     *            the message
      */
     public IllegalBlockSizeException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Creates a new {@code IllegalBlockSizeException}.
      */
     public IllegalBlockSizeException() {
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyAgreement.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyAgreement.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyAgreement.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyAgreement.java Sun Apr 26 12:30:01 2009
@@ -35,12 +35,11 @@
 import org.apache.harmony.crypto.internal.nls.Messages;
 import org.apache.harmony.security.fortress.Engine;
 
-
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class provides the functionality for a key exchange protocol. This
+ * enables two or more parties to agree on a secret key for symmetric
+ * cryptography.
  */
-
 public class KeyAgreement {
 
     // Used to access common engine functionality
@@ -59,8 +58,14 @@
     private final String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyAgreement} instance.
+     *
+     * @param keyAgreeSpi
+     *            the <b>SPI</b> delegate.
+     * @param provider
+     *            the provider providing this KeyAgreement.
+     * @param algorithm
+     *            the name of the key agreement algorithm.
      */
     protected KeyAgreement(KeyAgreementSpi keyAgreeSpi, Provider provider,
             String algorithm) {
@@ -70,24 +75,33 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the name of the key agreement algorithm.
+     *
+     * @return the name of the key agreement algorithm.
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the provider for this {@code KeyAgreement} instance.
+     *
+     * @return the provider for this {@code KeyAgreement} instance.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyAgreement} for the specified algorithm.
+     *
+     * @param algorithm
+     *            the name of the key agreement algorithm to create.
+     * @return a key agreement for the specified algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if no installed provider can provide the requested algorithm.
+     * @throws NullPointerException
+     *             if the specified algorithm is {@code null}.
      */
     public static final KeyAgreement getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -102,8 +116,23 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyAgreement} for the specified algorithm from the
+     * specified provider.
+     *
+     * @param algorithm
+     *            the name of the key agreement algorithm to create.
+     * @param provider
+     *            the name of the provider that provides the requested
+     *            algorithm.
+     * @return a key agreement for the specified algorithm from the specified
+     *         provider.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             algorithm.
+     * @throws NoSuchProviderException
+     *             if the specified provider does not exist.
+     * @throws IllegalArgumentException
+     *             if the specified provider name is {@code null} or empty.
      */
     public static final KeyAgreement getInstance(String algorithm,
             String provider) throws NoSuchAlgorithmException,
@@ -119,8 +148,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Create a new {@code KeyAgreement} for the specified algorithm from the
+     * specified provider.
+     *
+     * @param algorithm
+     *            the name of the key agreement algorithm to create.
+     * @param provider
+     *            the provider that provides the requested algorithm.
+     * @return a key agreement for the specified algorithm from the specified
+     *         provider.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             algorithm.
+     * @throws IllegalArgumentException
+     *             if the specified provider is {@code null}.
+     * @throws NullPointerException
+     *             if the specified algorithm name is {@code null}.
      */
     public static final KeyAgreement getInstance(String algorithm,
             Provider provider) throws NoSuchAlgorithmException {
@@ -138,16 +181,29 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyAgreement} with the specified key.
+     *
+     * @param key
+     *            the key to initialize this key agreement.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this key
+     *             agreement.
      */
     public final void init(Key key) throws InvalidKeyException {
         spiImpl.engineInit(key, rndm);//new SecureRandom());
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyAgreement} with the specified key and the
+     * specified randomness source.
+     *
+     * @param key
+     *            the key to initialize this key agreement.
+     * @param random
+     *            the source for any randomness needed.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this key
+     *             agreement.
      */
     public final void init(Key key, SecureRandom random)
             throws InvalidKeyException {
@@ -155,8 +211,19 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyAgreement} with the specified key and the
+     * algorithm parameters.
+     *
+     * @param key
+     *            the key to initialize this key agreement.
+     * @param params
+     *            the parameters for this key agreement algorithm.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this key
+     *             agreement.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters are invalid for this key
+     *             agreement algorithm.
      */
     public final void init(Key key, AlgorithmParameterSpec params)
             throws InvalidKeyException, InvalidAlgorithmParameterException {
@@ -164,8 +231,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyAgreement} with the specified key, algorithm
+     * parameters and randomness source.
+     *
+     * @param key
+     *            the key to initialize this key agreement.
+     * @param params
+     *            the parameters for this key agreement algorithm.
+     * @param random
+     *            the source for any randomness needed.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this key
+     *             agreement.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters are invalid for this key
+     *             agreement algorithm.
      */
     public final void init(Key key, AlgorithmParameterSpec params,
             SecureRandom random) throws InvalidKeyException,
@@ -174,8 +254,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Does the next (or the last) phase of the key agreement, using the
+     * specified key.
+     *
+     * @param key
+     *            the key received from the other party for this phase.
+     * @param lastPhase
+     *            set to {@code true} if this is the last phase of this key
+     *            agreement.
+     * @return the intermediate key from this phase or {@code null} if there is
+     *         no intermediate key for this phase.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used in this key agreement or
+     *             this phase,
+     * @throws IllegalStateException
+     *             if this instance has not been initialized.
      */
     public final Key doPhase(Key key, boolean lastPhase)
             throws InvalidKeyException, IllegalStateException {
@@ -183,16 +276,29 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates the shared secret.
+     *
+     * @return the generated shared secret.
+     * @throws IllegalStateException
+     *             if this key agreement is not complete.
      */
     public final byte[] generateSecret() throws IllegalStateException {
         return spiImpl.engineGenerateSecret();
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates the shared secret and stores it into the buffer {@code
+     * sharedSecred} at {@code offset}.
+     *
+     * @param sharedSecret
+     *            the buffer to store the shared secret.
+     * @param offset
+     *            the offset in the buffer.
+     * @return the number of bytes stored in the buffer.
+     * @throws IllegalStateException
+     *             if this key agreement is not complete.
+     * @throws ShortBufferException
+     *             if the specified buffer is too small for the shared secret.
      */
     public final int generateSecret(byte[] sharedSecret, int offset)
             throws IllegalStateException, ShortBufferException {
@@ -200,8 +306,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates the shared secret.
+     *
+     * @param algorithm
+     *            the algorithm to for the {@code SecretKey}
+     * @return the shared secret as a {@code SecretKey} of the specified
+     *         algorithm.
+     * @throws IllegalStateException
+     *             if this key agreement is not complete.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm for the secret key does not
+     *             exists.
+     * @throws InvalidKeyException
+     *             if a {@code SecretKey} with the specified algorithm cannot be
+     *             created using the generated shared secret.
      */
     public final SecretKey generateSecret(String algorithm)
             throws IllegalStateException, NoSuchAlgorithmException,

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyAgreementSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyAgreementSpi.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyAgreementSpi.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyAgreementSpi.java Sun Apr 26 12:30:01 2009
@@ -30,57 +30,115 @@
 import java.security.spec.AlgorithmParameterSpec;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The <i>Service Provider Interface</i> (<b>SPI</b>) definition for the
+ * {@code KeyAgreement} class.
  */
 public abstract class KeyAgreementSpi {
+
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyAgreementSpi} instance.
      */
-
     public KeyAgreementSpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Does the next (or the last) phase of the key agreement, using the
+     * specified key.
+     *
+     * @param key
+     *            the key received from the other party for this phase.
+     * @param lastPhase
+     *            set to {@code true} if this is the last phase of this key
+     *            agreement.
+     * @return the intermediate key from this phase or null if there is no
+     *         intermediate key for this phase.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used in this key agreement or
+     *             this phase,
+     * @throws IllegalStateException
+     *             if this instance has not been initialized.
      */
     protected abstract Key engineDoPhase(Key key, boolean lastPhase)
             throws InvalidKeyException, IllegalStateException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates the shared secret.
+     *
+     * @return the generated shared secret.
+     * @throws IllegalStateException
+     *             if this key agreement is not complete.
      */
     protected abstract byte[] engineGenerateSecret()
             throws IllegalStateException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates the shared secret and stores it into the buffer {@code
+     * sharedSecred} at {@code offset}.
+     *
+     * @param sharedSecret
+     *            the buffer to store the shared secret.
+     * @param offset
+     *            the offset in the buffer.
+     * @return the number of bytes stored in the buffer.
+     * @throws IllegalStateException
+     *             if this key agreement is not complete.
+     * @throws ShortBufferException
+     *             if the specified buffer is too small for the shared secret.
      */
     protected abstract int engineGenerateSecret(byte[] sharedSecret, int offset)
             throws IllegalStateException, ShortBufferException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates the shared secret.
+     *
+     * @param algorithm
+     *            the algorithm to for the {@code SecretKey}
+     * @return the shared secret as a {@code SecretKey} of the specified
+     *         algorithm.
+     * @throws IllegalStateException
+     *             if this key agreement is not complete.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm for the secret key does not
+     *             exists.
+     * @throws InvalidKeyException
+     *             if a {@code SecretKey} with the specified algorithm cannot be
+     *             created using the generated shared secret.
      */
     protected abstract SecretKey engineGenerateSecret(String algorithm)
             throws IllegalStateException, NoSuchAlgorithmException,
             InvalidKeyException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyAgreementSpi} with the specified key and the
+     * specified randomness source.
+     *
+     * @param key
+     *            the key to initialize this key agreement.
+     * @param random
+     *            the source for any randomness needed.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this key
+     *             agreement.
      */
     protected abstract void engineInit(Key key, SecureRandom random)
             throws InvalidKeyException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyAgreementSpi} with the specified key,
+     * algorithm parameters and randomness source.
+     *
+     * @param key
+     *            the key to initialize this key agreement.
+     * @param params
+     *            the parameters for this key agreement algorithm.
+     * @param random
+     *            the source for any randomness needed.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this key
+     *             agreement.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters are invalid for this key
+     *             agreement algorithm.
      */
     protected abstract void engineInit(Key key, AlgorithmParameterSpec params,
             SecureRandom random) throws InvalidKeyException,

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyGenerator.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyGenerator.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyGenerator.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyGenerator.java Sun Apr 26 12:30:01 2009
@@ -35,10 +35,9 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class provides the public API for generating symmetric cryptographic
+ * keys.
  */
-
 public class KeyGenerator {
 
     // Used to access common engine functionality
@@ -57,8 +56,14 @@
     private final String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyGenerator} instance.
+     *
+     * @param keyGenSpi
+     *            the implementation delegate.
+     * @param provider
+     *            the implementation provider.
+     * @param algorithm
+     *            the name of the algorithm.
      */
     protected KeyGenerator(KeyGeneratorSpi keyGenSpi, Provider provider,
             String algorithm) {
@@ -68,24 +73,34 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the name of the key generation algorithm.
+     *
+     * @return the name of the key generation algorithm.
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the provider of this {@code KeyGenerator} instance.
+     *
+     * @return the provider of this {@code KeyGenerator} instance.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyGenerator} instance that provides the specified
+     * key algorithm,
+     *
+     * @param algorithm
+     *            the name of the requested key algorithm
+     * @return the new {@code KeyGenerator} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available by any provider.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null}.
      */
     public static final KeyGenerator getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -100,8 +115,23 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyGenerator} instance that provides the specified
+     * key algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the requested key algorithm.
+     * @param provider
+     *            the name of the provider that is providing the algorithm.
+     * @return the new {@code KeyGenerator} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not provided by the specified
+     *             provider.
+     * @throws NoSuchProviderException
+     *             if the specified provider is not available.
+     * @throws IllegalArgumentException
+     *             if the specified provider is name is {@code null} or empty.
+     * @throws NullPointerException
+     *             if the specified algorithm name is {@code null}.
      */
     public static final KeyGenerator getInstance(String algorithm,
             String provider) throws NoSuchAlgorithmException,
@@ -117,8 +147,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyGenerator} instance that provides the specified
+     * key algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the requested key algorithm.
+     * @param provider
+     *            the provider that is providing the algorithm
+     * @return the new {@code KeyGenerator} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not provided by the specified
+     *             provider.
+     * @throws IllegalArgumentException
+     *             if the specified provider is {@code null}.
+     * @throws NullPointerException
+     *             if the specified algorithm name is {@code null}.
      */
     public static final KeyGenerator getInstance(String algorithm,
             Provider provider) throws NoSuchAlgorithmException {
@@ -136,16 +179,23 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates a secret key.
+     *
+     * @return the generated secret key.
      */
     public final SecretKey generateKey() {
         return spiImpl.engineGenerateKey();
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyGenerator} instance with the specified
+     * algorithm parameters.
+     *
+     * @param params
+     *            the parameters for the key generation algorithm.
+     * @throws InvalidAlgorithmParameterException
+     *             if the parameters cannot be used to initialize this key
+     *             generator algorithm.
      */
     public final void init(AlgorithmParameterSpec params)
             throws InvalidAlgorithmParameterException {
@@ -153,8 +203,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyGenerator} instance with the specified
+     * algorithm parameters and randomness source.
+     *
+     * @param params
+     *            the parameters for the key generation algorithm.
+     * @param random
+     *            the randomness source for any random bytes.
+     * @throws InvalidAlgorithmParameterException
+     *             if the parameters cannot be uses to initialize this key
+     *             generator algorithm.
      */
     public final void init(AlgorithmParameterSpec params, SecureRandom random)
             throws InvalidAlgorithmParameterException {
@@ -162,24 +220,35 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyGenerator} instance for the specified key size
+     * (in bits).
+     *
+     * @param keysize
+     *            the size of the key (in bits).
      */
     public final void init(int keysize) {
         spiImpl.engineInit(keysize, rndm);//new SecureRandom());
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyGenerator} instance for the specified key size
+     * (in bits) using the specified randomness source.
+     *
+     * @param keysize
+     *            the size of the key (in bits).
+     * @param random
+     *            the randomness source for any random bytes.
      */
     public final void init(int keysize, SecureRandom random) {
         spiImpl.engineInit(keysize, random);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyGenerator} with the specified randomness
+     * source.
+     *
+     * @param random
+     *            the randomness source for any random bytes.
      */
     public final void init(SecureRandom random) {
         spiImpl.engineInit(random);

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyGeneratorSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyGeneratorSpi.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyGeneratorSpi.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/KeyGeneratorSpi.java Sun Apr 26 12:30:01 2009
@@ -27,39 +27,58 @@
 import java.security.spec.AlgorithmParameterSpec;
 
 /**
- * @com.intel.drl.spec_ref
+ * The <i>Service Provider Interface</i> (<b>SPI</b>) definition for the
+ * {@code KeyGenerator} class.
  * 
+ * @see KeyGenerator
  */
 public abstract class KeyGeneratorSpi {
+
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code KeyGeneratorSpi} instance.
      */
     public KeyGeneratorSpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generates a secret key.
+     *
+     * @return the generated secret key.
      */
     protected abstract SecretKey engineGenerateKey();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyGeneratorSpi} instance with the specified
+     * algorithm parameters and randomness source.
+     *
+     * @param params
+     *            the parameters for the key generation algorithm.
+     * @param random
+     *            the randomness source for any random bytes.
+     * @throws InvalidAlgorithmParameterException
+     *             if the parameters cannot be uses to initialize this key
+     *             generator algorithm.
      */
     protected abstract void engineInit(AlgorithmParameterSpec params,
             SecureRandom random) throws InvalidAlgorithmParameterException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyGenerator} instance for the specified key
+     * size (in bits) using the specified randomness source.
+     *
+     * @param keysize
+     *            the size of the key (in bits).
+     * @param random
+     *            the randomness source for any random bytes.
      */
     protected abstract void engineInit(int keysize, SecureRandom random);
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code KeyGenerator} with the specified randomness
+     * source.
+     *
+     * @param random
+     *            the randomness source for any random bytes.
      */
     protected abstract void engineInit(SecureRandom random);
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/Mac.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/Mac.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/Mac.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/Mac.java Sun Apr 26 12:30:01 2009
@@ -37,10 +37,9 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class provides the public API for <i>Message Authentication Code</i>
+ * (MAC) algorithms.
  */
-
 public class Mac implements Cloneable {
 
     //Used to access common engine functionality
@@ -59,8 +58,14 @@
     private boolean isInitMac;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code Mac} instance.
+     *
+     * @param macSpi
+     *            the implementation delegate.
+     * @param provider
+     *            the implementation provider.
+     * @param algorithm
+     *            the name of the MAC algorithm.
      */
     protected Mac(MacSpi macSpi, Provider provider, String algorithm) {
         this.provider = provider;
@@ -70,26 +75,35 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the name of the MAC algorithm.
+     * 
+     * @return the name of the MAC algorithm.
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the provider of this {@code Mac} instance.
+     *
+     * @return the provider of this {@code Mac} instance.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code Mac} instance that provides the specified MAC
+     * algorithm.
      * 
-     * throws NullPointerException if algorithm is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
+     * @param algorithm
+     *            the name of the requested MAC algorithm.
+     * @return the new {@code Mac} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not available by any provider.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release).
      */
     public static final Mac getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -103,10 +117,24 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code Mac} instance that provides the specified MAC
+     * algorithm from the specified provider.
      * 
-     * throws NullPointerException if algorithm is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
+     * @param algorithm
+     *            the name of the requested MAC algorithm.
+     * @param provider
+     *            the name of the provider that is providing the algorithm.
+     * @return the new {@code Mac} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not provided by the specified
+     *             provider.
+     * @throws NoSuchProviderException
+     *             if the specified provider is not available.
+     * @throws IllegalArgumentException
+     *             if the specified provider name is {@code null} or empty.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release).
      */
     public static final Mac getInstance(String algorithm, String provider)
             throws NoSuchAlgorithmException, NoSuchProviderException {
@@ -121,10 +149,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code Mac} instance that provides the specified MAC
+     * algorithm from the specified provider.
      * 
-     * throws NullPointerException if algorithm is null (instead of
-     * NoSuchAlgorithmException as in 1.4 release)
+     * @param algorithm
+     *            the name of the requested MAC algorithm.
+     * @param provider
+     *            the provider that is providing the algorithm.
+     * @return the new {@code Mac} instance.
+     * @throws NoSuchAlgorithmException
+     *             if the specified algorithm is not provided by the specified
+     *             provider.
+     * @throws IllegalArgumentException
+     *             if {@code provider} is {@code null}.
+     * @throws NullPointerException
+     *             if {@code algorithm} is {@code null} (instead of
+     *             NoSuchAlgorithmException as in 1.4 release).
      */
     public static final Mac getInstance(String algorithm, Provider provider)
             throws NoSuchAlgorithmException {
@@ -141,16 +181,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the length of this MAC (in bytes).
+     *
+     * @return the length of this MAC (in bytes).
      */
     public final int getMacLength() {
         return spiImpl.engineGetMacLength();
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code Mac} instance with the specified key and
+     * algorithm parameters.
+     *
+     * @param key
+     *            the key to initialize this algorithm.
+     * @param params
+     *            the parameters for this algorithm.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this
+     *             algorithm, or it is null.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters cannot be used to initialize this
+     *             algorithm.
      */
     public final void init(Key key, AlgorithmParameterSpec params)
             throws InvalidKeyException, InvalidAlgorithmParameterException {
@@ -162,8 +214,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code Mac} instance with the specified key.
+     *
+     * @param key
+     *            the key to initialize this algorithm.
+     * @throws InvalidKeyException
+     *             if initialization fails because the provided key is {@code
+     *             null}.
+     * @throws RuntimeException
+     *             if the specified key cannot be used to initialize this
+     *             algorithm.
      */
     public final void init(Key key) throws InvalidKeyException {
         if (key == null) {
@@ -178,8 +238,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates this {@code Mac} instance with the specified byte.
+     *
+     * @param input
+     *            the byte
+     * @throws IllegalStateException
+     *             if this MAC is not initialized.
      */
     public final void update(byte input) throws IllegalStateException {
         if (!isInitMac) {
@@ -189,8 +253,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates this {@code Mac} instance with the data from the specified buffer
+     * {@code input} from the specified {@code offset} and length {@code len}.
+     *
+     * @param input
+     *            the buffer.
+     * @param offset
+     *            the offset in the buffer.
+     * @param len
+     *            the length of the data in the buffer.
+     * @throws IllegalStateException
+     *             if this MAC is not initialized.
+     * @throws IllegalArgumentException
+     *             if {@code offset} and {@code len} do not specified a valid
+     *             chunk in {@code input} buffer.
      */
     public final void update(byte[] input, int offset, int len)
             throws IllegalStateException {
@@ -207,8 +283,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Copies the buffer provided as input for further processing.
+     *
+     * @param input
+     *            the buffer.
+     * @throws IllegalStateException
+     *             if this MAC is not initialized.
      */
     public final void update(byte[] input) throws IllegalStateException {
         if (!isInitMac) {
@@ -220,8 +300,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates this {@code Mac} instance with the data from the specified
+     * buffer, starting at {@link ByteBuffer#position()}, including the next
+     * {@link ByteBuffer#remaining()} bytes.
+     *
+     * @param input
+     *            the buffer.
+     * @throws IllegalStateException
+     *             if this MAC is not initialized.
      */
     public final void update(ByteBuffer input) {
         if (!isInitMac) {
@@ -235,8 +321,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Computes the digest of this MAC based on the data previously specified in
+     * {@link #update} calls.
+     * <p>
+     * This {@code Mac} instance is reverted to its initial state and can be
+     * used to start the next MAC computation with the same parameters or
+     * initialized with different parameters.
+     *
+     * @return the generated digest.
+     * @throws IllegalStateException
+     *             if this MAC is not initialized.
      */
     public final byte[] doFinal() throws IllegalStateException {
         if (!isInitMac) {
@@ -246,8 +340,25 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Computes the digest of this MAC based on the data previously specified in
+     * {@link #update} calls and stores the digest in the specified {@code
+     * output} buffer at offset {@code outOffset}.
+     * <p>
+     * This {@code Mac} instance is reverted to its initial state and can be
+     * used to start the next MAC computation with the same parameters or
+     * initialized with different parameters.
+     *
+     * @param output
+     *            the output buffer
+     * @param outOffset
+     *            the offset in the output buffer
+     * @throws ShortBufferException
+     *             if the specified output buffer is either too small for the
+     *             digest to be stored, the specified output buffer is {@code
+     *             null}, or the specified offset is negative or past the length
+     *             of the output buffer.
+     * @throws IllegalStateException
+     *             if this MAC is not initialized.
      */
     public final void doFinal(byte[] output, int outOffset)
             throws ShortBufferException, IllegalStateException {
@@ -273,8 +384,19 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Computes the digest of this MAC based on the data previously specified on
+     * {@link #update} calls and on the final bytes specified by {@code input}
+     * (or based on those bytes only).
+     * <p>
+     * This {@code Mac} instance is reverted to its initial state and can be
+     * used to start the next MAC computation with the same parameters or
+     * initialized with different parameters.
+     *
+     * @param input
+     *            the final bytes.
+     * @return the generated digest.
+     * @throws IllegalStateException
+     *             if this MAC is not initialized.
      */
     public final byte[] doFinal(byte[] input) throws IllegalStateException {
         if (!isInitMac) {
@@ -287,16 +409,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Resets this {@code Mac} instance to its initial state.
+     * <p>
+     * This {@code Mac} instance is reverted to its initial state and can be
+     * used to start the next MAC computation with the same parameters or
+     * initialized with different parameters.
      */
     public final void reset() {
         spiImpl.engineReset();
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Clones this {@code Mac} instance and the underlying implementation.
+     *
+     * @return the cloned instance.
+     * @throws CloneNotSupportedException
+     *             if the underlying implementation does not support cloning.
      */
     @Override
     public final Object clone() throws CloneNotSupportedException {

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/MacSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/MacSpi.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/MacSpi.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/MacSpi.java Sun Apr 26 12:30:01 2009
@@ -29,46 +29,73 @@
 import java.nio.ByteBuffer;
 
 /**
- * @com.intel.drl.spec_ref
+ * The <i>Service-Provider Interface</i> (<b>SPI</b>) definition for the {@code
+ * Mac} class.
  * 
+ * @see Mac
  */
-
 public abstract class MacSpi {
+
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code MacSpi} instance.
      */
     public MacSpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the length of this MAC (in bytes).
+     *
+     * @return the length of this MAC (in bytes).
      */
     protected abstract int engineGetMacLength();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this {@code MacSpi} instance with the specified key and
+     * algorithm parameters.
+     *
+     * @param key
+     *            the key to initialize this algorithm.
+     * @param params
+     *            the parameters for this algorithm.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this
+     *             algorithm, or it is {@code null}.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters cannot be used to initialize this
+     *             algorithm.
      */
     protected abstract void engineInit(Key key, AlgorithmParameterSpec params)
             throws InvalidKeyException, InvalidAlgorithmParameterException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates this {@code MacSpi} instance with the specified byte.
+     *
+     * @param input
+     *            the byte.
      */
     protected abstract void engineUpdate(byte input);
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates this {@code MacSpi} instance with the data from the specified
+     * buffer {@code input} from the specified {@code offset} and length {@code
+     * len}.
+     *
+     * @param input
+     *            the buffer.
+     * @param offset
+     *            the offset in the buffer.
+     * @param len
+     *            the length of the data in the buffer.
      */
     protected abstract void engineUpdate(byte[] input, int offset, int len);
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Updates this {@code MacSpi} instance with the data from the specified
+     * buffer, starting at {@link ByteBuffer#position()}, including the next
+     * {@link ByteBuffer#remaining()} bytes.
+     *
+     * @param input
+     *            the buffer.
      */
     protected void engineUpdate(ByteBuffer input) {
         if (!input.hasRemaining()) {
@@ -90,20 +117,32 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Computes the digest of this MAC based on the data previously specified in
+     * {@link #engineUpdate} calls.
+     * <p>
+     * This {@code MacSpi} instance is reverted to its initial state and
+     * can be used to start the next MAC computation with the same parameters or
+     * initialized with different parameters.
+     *
+     * @return the generated digest.
      */
     protected abstract byte[] engineDoFinal();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Resets this {@code MacSpi} instance to its initial state.
+     * <p>
+     * This {@code MacSpi} instance is reverted to its initial state and can be
+     * used to start the next MAC computation with the same parameters or
+     * initialized with different parameters.
      */
     protected abstract void engineReset();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Clones this {@code MacSpi} instance.
+     *
+     * @return the cloned instance.
+     * @throws CloneNotSupportedException
+     *             if cloning is not supported.
      */
     @Override
     public Object clone() throws CloneNotSupportedException {

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/NoSuchPaddingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/NoSuchPaddingException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/NoSuchPaddingException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/NoSuchPaddingException.java Sun Apr 26 12:30:01 2009
@@ -25,8 +25,8 @@
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception that is thrown when the requested padding mechanism is not
+ * supported.
  */
 public class NoSuchPaddingException extends GeneralSecurityException {
 
@@ -36,16 +36,18 @@
     private static final long serialVersionUID = -4572885201200175466L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code NoSuchPaddingException} with the specified
+     * message.
      * 
+     * @param msg
+     *            the message.
      */
     public NoSuchPaddingException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Creates a new {@code NoSuchPaddingException}.
      */
     public NoSuchPaddingException() {
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/NullCipher.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/NullCipher.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/NullCipher.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/NullCipher.java Sun Apr 26 12:30:01 2009
@@ -30,14 +30,13 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- *
+ * This class provides an identity cipher that does not transform the input data
+ * in any way. The <i>encrypted</i> data is identical to the <i>plain text</i>.
  */
 public class NullCipher extends Cipher {
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Creates a new {@code NullCipher} instance.
      */
     public NullCipher() {
         super(new NullCipherSpi(), null, null);

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SealedObject.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SealedObject.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SealedObject.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SealedObject.java Sun Apr 26 12:30:01 2009
@@ -40,7 +40,15 @@
 import org.apache.harmony.crypto.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
+ * A {@code SealedObject} is a wrapper around a {@code serializable} object
+ * instance and encrypts it using a cryptographic cipher.
+ * <p>
+ * Since a {@code SealedObject} instance is a serializable object itself it can
+ * either be stored or transmitted over an insecure channel.
+ * <p>
+ * The wrapped object can later be decrypted (unsealed) using the corresponding
+ * key and then be deserialized to retrieve the original object.The sealed
+ * object itself keeps track of the cipher and corresponding parameters.
  */
 public class SealedObject implements Serializable {
 
@@ -51,7 +59,7 @@
     private static final long serialVersionUID = 4482838265551344752L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * The {@link AlgorithmParameters} in encoded format.
      */
     protected byte[] encodedParams;
     private byte[] encryptedContent;
@@ -67,7 +75,23 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code SealedObject} instance wrapping the specified object
+     * and sealing it using the specified cipher.
+     * <p>
+     * The cipher must be fully initialized.
+     *
+     * @param object
+     *            the object to seal, can be {@code null}.
+     * @param c
+     *            the cipher to encrypt the object.
+     * @throws IOException
+     *             if the serialization fails.
+     * @throws IllegalBlockSizeException
+     *             if the specified cipher is a block cipher and the length of
+     *             the serialized data is not a multiple of the ciphers block
+     *             size.
+     * @throws NullPointerException
+     *             if the cipher is {@code null}.
      */
     public SealedObject(Serializable object, Cipher c)
                 throws IOException, IllegalBlockSizeException {
@@ -92,7 +116,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code SealedObject} instance by copying the data from
+     * the specified object.
+     *
+     * @param so
+     *            the object to copy.
      */
     protected SealedObject(SealedObject so) {
         if (so == null) {
@@ -105,14 +133,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the algorithm this object was sealed with.
+     *
+     * @return the algorithm this object was sealed with.
      */
     public final String getAlgorithm() {
         return sealAlg;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the wrapped object, decrypting it using the specified key.
+     *
+     * @param key
+     *            the key to decrypt the data with.
+     * @return the encapsulated object.
+     * @throws IOException
+     *             if deserialization fails.
+     * @throws ClassNotFoundException
+     *             if deserialization fails.
+     * @throws NoSuchAlgorithmException
+     *             if the algorithm to decrypt the data is not available.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to decrypt the data.
      */
     public final Object getObject(Key key)
                 throws IOException, ClassNotFoundException,
@@ -155,7 +197,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the wrapped object, decrypting it using the specified
+     * cipher.
+     *
+     * @param c
+     *            the cipher to decrypt the data.
+     * @return the encapsulated object.
+     * @throws IOException
+     *             if deserialization fails.
+     * @throws ClassNotFoundException
+     *             if deserialization fails.
+     * @throws IllegalBlockSizeException
+     *             if the specified cipher is a block cipher and the length of
+     *             the serialized data is not a multiple of the ciphers block
+     *             size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
      */
     public final Object getObject(Cipher c)
                 throws IOException, ClassNotFoundException,
@@ -171,7 +228,24 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the wrapped object, decrypting it using the specified key. The
+     * specified provider is used to retrieve the cipher algorithm.
+     *
+     * @param key
+     *            the key to decrypt the data.
+     * @param provider
+     *            the name of the provider that provides the cipher algorithm.
+     * @return the encapsulated object.
+     * @throws IOException
+     *             if deserialization fails.
+     * @throws ClassNotFoundException
+     *             if deserialization fails.
+     * @throws NoSuchAlgorithmException
+     *             if the algorithm used to decrypt the data is not available.
+     * @throws NoSuchProviderException
+     *             if the specified provider is not available.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to decrypt the data.
      */
     public final Object getObject(Key key, String provider)
                 throws IOException, ClassNotFoundException,

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKey.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKey.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKey.java Sun Apr 26 12:30:01 2009
@@ -25,15 +25,22 @@
 import java.security.Key;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * A cryptographic secret (symmetric) key.
+ * <p>
+ * This interface is a <i>marker interface</i> to group secret keys and to
+ * provide type safety for.
+ * <p>
+ * Implementations of this interface have to overwrite the
+ * {@link Object#equals(Object) equals} and {@link Object#hashCode() hashCode}
+ * from {@link java.lang.Object} so comparison is done using the actual key data
+ * and not the object reference.
  */
 public interface SecretKey extends Key {
 
     /**
-     * @com.intel.drl.spec_ref
+     * The serialization version identifier.
+     *
      * @serial
-     *  
      */
     public static final long serialVersionUID = -4795878709595146952L;
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKeyFactory.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKeyFactory.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKeyFactory.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKeyFactory.java Sun Apr 26 12:30:01 2009
@@ -35,8 +35,16 @@
 
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The public API for {@code SecretKeyFactory} implementations.
+ * <p>
+ * Secret key factories provide the following functionality:
+ * <ul>
+ * <li>convert {@link SecretKey} objects to and from {@link KeySpec} objects</li>
+ * <li>translate {@link SecretKey} objects from one provider implementation to
+ * another</li>
+ * </ul>
+ * Which key specifications are supported by the {@link #generateSecret} and
+ * {@link #getKeySpec} is provider dependent.
  */
 public class SecretKeyFactory {
 
@@ -53,8 +61,14 @@
     private final String algorithm;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code SecretKeyFactory}
+     *
+     * @param keyFacSpi
+     *            the SPI delegate.
+     * @param provider
+     *            the provider providing this key factory.
+     * @param algorithm
+     *            the algorithm name for the secret key.
      */
     protected SecretKeyFactory(SecretKeyFactorySpi keyFacSpi,
             Provider provider, String algorithm) {
@@ -64,24 +78,34 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the name of the secret key algorithm.
+     *
+     * @return the name of the secret key algorithm.
      */
     public final String getAlgorithm() {
         return algorithm;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the provider for this {@code SecretKeyFactory} instance.
+     *
+     * @return the provider for this {@code SecretKeyFactory} instance.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code SecretKeyFactory} instance for the specified key
+     * algorithm.
+     *
+     * @param algorithm
+     *            the name of the key algorithm.
+     * @return a secret key factory for the specified key algorithm.
+     * @throws NoSuchAlgorithmException
+     *             if no installed provider can provide the requested algorithm.
+     * @throws NullPointerException
+     *             if the specified algorithm is {@code null}.
      */
     public static final SecretKeyFactory getInstance(String algorithm)
             throws NoSuchAlgorithmException {
@@ -96,8 +120,23 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code SecretKeyFactory} instance for the specified key
+     * algorithm from the specified {@code provider}.
+     *
+     * @param algorithm
+     *            the name of the key algorithm.
+     * @param provider
+     *            the name of the provider that provides the requested
+     *            algorithm.
+     * @return a secret key factory for the specified key algorithm from the
+     *         specified provider.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provide the requested
+     *             algorithm.
+     * @throws NoSuchProviderException
+     *             if the specified provider does not exist.
+     * @throws IllegalArgumentException
+     *             if the specified provider name is {@code null} or empty.
      */
     public static final SecretKeyFactory getInstance(String algorithm,
             String provider) throws NoSuchAlgorithmException,
@@ -113,8 +152,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code SecretKeyFactory} instance for the specified key
+     * algorithm from the specified provider.
+     *
+     * @param algorithm
+     *            the name of the key algorithm.
+     * @param provider
+     *            the provider that provides the requested algorithm.
+     * @return a secret key factory for the specified key algorithm from the
+     *         specified provider.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider cannot provider the requested
+     *             algorithm.
+     * @throws IllegalArgumentException
+     *             if the specified provider is {@code null}.
+     * @throws NullPointerException
+     *             is the specified algorithm name is {@code null}.
      */
     public static final SecretKeyFactory getInstance(String algorithm,
             Provider provider) throws NoSuchAlgorithmException {
@@ -132,8 +185,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generate a secret key from the specified key specification.
+     *
+     * @param keySpec
+     *            the key specification.
+     * @return a secret key.
+     * @throws InvalidKeySpecException
+     *             if the specified key specification cannot be used to generate
+     *             a secret key.
      */
     public final SecretKey generateSecret(KeySpec keySpec)
             throws InvalidKeySpecException {
@@ -141,8 +200,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the key specification of the specified secret key.
+     *
+     * @param key
+     *            the secret key to get the specification from.
+     * @param keySpec
+     *            the target key specification class.
+     * @return an instance of the specified key specification class.
+     * @throws InvalidKeySpecException
+     *             if the specified secret key cannot be transformed into the
+     *             requested key specification.
      */
     @SuppressWarnings("unchecked")
     public final KeySpec getKeySpec(SecretKey key, Class keySpec)
@@ -151,8 +218,15 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Translates the specified secret key into an instance of the corresponding
+     * key from the provider of this key factory.
+     *
+     * @param key
+     *            the secret key to translate.
+     * @return the corresponding translated key.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be translated using this key
+     *             factory.
      */
     public final SecretKey translateKey(SecretKey key)
             throws InvalidKeyException {

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKeyFactorySpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKeyFactorySpi.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKeyFactorySpi.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/SecretKeyFactorySpi.java Sun Apr 26 12:30:01 2009
@@ -27,36 +27,56 @@
 import java.security.spec.KeySpec;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The <i>Service Provider Interface</i> (<b>SPI</b>) definition for the {@code
+ * SecretKeyFactory} class.
  */
 public abstract class SecretKeyFactorySpi {
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code SecretKeyFactorySpi} instance.
      */
     public SecretKeyFactorySpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Generate a secret key from the specified key specification.
+     *
+     * @param keySpec
+     *            the key specification.
+     * @return a secret key.
+     * @throws InvalidKeySpecException
+     *             if the specified key specification cannot be used to generate
+     *             a secret key.
      */
     protected abstract SecretKey engineGenerateSecret(KeySpec keySpec)
             throws InvalidKeySpecException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the key specification of the specified secret key.
+     *
+     * @param key
+     *            the secret key to get the specification from.
+     * @param keySpec
+     *            the target key specification class.
+     * @return an instance of the specified key specification class.
+     * @throws InvalidKeySpecException
+     *             if the specified secret key cannot be transformed into the
+     *             requested key specification.
      */
     @SuppressWarnings("unchecked")
     protected abstract KeySpec engineGetKeySpec(SecretKey key, Class keySpec)
             throws InvalidKeySpecException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Translates the specified secret key into an instance of the corresponding
+     * key from the provider of this key factory.
+     *
+     * @param key
+     *            the secret key to translate.
+     * @return the corresponding translated key.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be translated using this key
+     *             factory.
      */
     protected abstract SecretKey engineTranslateKey(SecretKey key)
             throws InvalidKeyException;

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ShortBufferException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ShortBufferException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ShortBufferException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/ShortBufferException.java Sun Apr 26 12:30:01 2009
@@ -25,8 +25,8 @@
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The exception that is thrown when the result of an operation is attempted to
+ * store in a user provided buffer that is too small.
  */
 public class ShortBufferException extends GeneralSecurityException {
 
@@ -36,16 +36,18 @@
     private static final long serialVersionUID = 8427718640832943747L;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new instance of {@code ShortBufferException} with the
+     * specified message
      * 
+     * @param msg
+     *            the exception message.
      */
     public ShortBufferException(String msg) {
         super(msg);
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     * 
+     * Creates a new instance of {@code ShortBufferException}.
      */
     public ShortBufferException() {
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHKey.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHKey.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHKey.java Sun Apr 26 12:30:01 2009
@@ -25,14 +25,14 @@
 import javax.crypto.spec.DHParameterSpec;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface for a Diffie-Hellman key.
  */
 public interface DHKey {
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the parameters for this key.
+     *
+     * @return the parameters for this key.
      */
     public DHParameterSpec getParams();
 }

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHPrivateKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHPrivateKey.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHPrivateKey.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHPrivateKey.java Sun Apr 26 12:30:01 2009
@@ -26,20 +26,18 @@
 import java.security.PrivateKey;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface for a private key in the Diffie-Hellman key exchange protocol.
  */
 public interface DHPrivateKey extends DHKey, PrivateKey {
 
     /**
-     * @com.intel.drl.spec_ref
-     * @serial
+     * The serialization version identifier.
      */
     public static final long serialVersionUID = 2211791113380396553L;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns this key's private value x.
+     * @return this key's private value x.
      */
     public BigInteger getX();
 

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHPublicKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHPublicKey.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHPublicKey.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/DHPublicKey.java Sun Apr 26 12:30:01 2009
@@ -26,20 +26,18 @@
 import java.security.PublicKey;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface for a public key in the Diffie-Hellman key exchange protocol.
  */
 public interface DHPublicKey extends DHKey, PublicKey {
 
     /**
-     * @com.intel.drl.spec_ref
-     * @serial
+     * The serial version identifier.
      */
     public static final long serialVersionUID = -6628103563352519193L;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns this key's public value Y.
+     * @return this key's public value Y.
      */
     public BigInteger getY();
 }
\ No newline at end of file

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/PBEKey.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/PBEKey.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/PBEKey.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/interfaces/PBEKey.java Sun Apr 26 12:30:01 2009
@@ -25,32 +25,33 @@
 import javax.crypto.SecretKey;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * The interface to a <i>password-based-encryption</i>  key.
  */
 public interface PBEKey extends SecretKey {
 
     /**
-     * @com.intel.drl.spec_ref
-     * @serial
+     * The serial version identifier.
      */
     public static final long serialVersionUID = -1430015993304333921L;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the iteration count, 0 if not specified.
+     *
+     * @return the iteration count, 0 if not specified.
      */
     public int getIterationCount();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns a copy of the salt data or null if not specified.
+     *
+     * @return a copy of the salt data or null if not specified.
      */
     public byte[] getSalt();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns a copy to the password.
+     *
+     * @return a copy to the password.
      */
     public char[] getPassword();
 



Mime
View raw message