harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [4/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/Cipher.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/Cipher.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/Cipher.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/Cipher.java Sun Apr 26 12:30:01 2009
@@ -44,50 +44,63 @@
 import org.apache.harmony.security.fortress.Engine;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class provides access to implementations of cryptographic ciphers for
+ * encryption and decryption. Cipher classes can not be instantiated directly,
+ * one has to call the Cipher's {@code getInstance} method with the name of a
+ * requested transformation, optionally with a provider. A transformation
+ * specifies an operation (or a set of operations) as a string in the form:
+ * <ul>
+ * <li><i>"algorithm/mode/padding"</i></li> or
+ * <li><i>"algorithm"</i></li>
+ * </ul>
+ * <i>algorithm</i> is the name of a cryptographic algorithm, <i>mode</i> is the
+ * name of a feedback mode and <i>padding</i> is the name of a padding scheme.
+ * If <i>mode</i> and/or <i>padding</i> values are omitted, provider specific
+ * default values will be used.
+ * <p>
+ * A valid transformation would be:
+ * <ul>
+ * {@code Cipher c = Cipher.getInstance("AES/CBC/PKCS5Padding");}
+ * </ul>
+ * When a block cipher is requested in in stream cipher mode, the number of bits
+ * to be processed at a time can be optionally specified by appending it to the
+ * mode name. e.g. <i>"AES/CFB8/NoPadding"</i>. If no number is specified, a
+ * provider specific default value is used.
  */
 public class Cipher {
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant for decryption operation mode.
      */
     public static final int DECRYPT_MODE = 2;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant for encryption operation mode.
      */
     public static final int ENCRYPT_MODE = 1;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant indicating that the key to be unwrapped is a private key.
      */
     public static final int PRIVATE_KEY = 2;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant indicating that the key to be unwrapped is a public key.
      */
     public static final int PUBLIC_KEY = 1;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant indicating that the key to be unwrapped is a secret key.
      */
     public static final int SECRET_KEY = 3;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant for key unwrapping operation mode.
      */
     public static final int UNWRAP_MODE = 4;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Constant for key wrapping operation mode.
      */
     public static final int WRAP_MODE = 3;
 
@@ -99,12 +112,12 @@
     private static final String SERVICE = "Cipher"; //$NON-NLS-1$
 
     /**
-     * Used to access common engine functionality
+     * Used to access common engine functionality.
      */
     private static final Engine engine = new Engine(SERVICE);
 
     /**
-     * The provider
+     * The provider.
      */
     private Provider provider;
 
@@ -121,8 +134,17 @@
     private static SecureRandom sec_rand;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new Cipher instance.
+     *
+     * @param cipherSpi
+     *            the implementation delegate of the cipher.
+     * @param provider
+     *            the provider of the implementation of this cipher.
+     * @param transformation
+     *            the name of the transformation that this cipher performs.
+     * @throws NullPointerException
+     *             if either cipherSpi is {@code null} or provider is {@code
+     *             null} and {@code cipherSpi} is a {@code NullCipherSpi}.
      */
     protected Cipher(CipherSpi cipherSpi, Provider provider,
             String transformation) {
@@ -138,8 +160,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new Cipher for the specified transformation. The installed
+     * providers are searched in order for an implementation of the specified
+     * transformation. The first found provider providing the transformation is
+     * used to create the cipher. If no provider is found an exception is
+     * thrown.
+     *
+     * @param transformation
+     *            the name of the transformation to create a cipher for.
+     * @return a cipher for the requested transformation.
+     * @throws NoSuchAlgorithmException
+     *             if no installed provider can provide the
+     *             <i>transformation</i>, or it is {@code null}, empty or in an
+     *             invalid format.
+     * @throws NoSuchPaddingException
+     *             if no installed provider can provide the padding scheme in
+     *             the <i>transformation</i>.
      */
     public static final Cipher getInstance(String transformation)
             throws NoSuchAlgorithmException, NoSuchPaddingException {
@@ -147,8 +183,25 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new cipher for the specified transformation provided by the
+     * specified provider.
+     *
+     * @param transformation
+     *            the name of the transformation to create a cipher for.
+     * @param provider
+     *            the name of the provider to ask for the transformation.
+     * @return a cipher for the requested transformation.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider can not provide the
+     *             <i>transformation</i>, or it is {@code null}, empty or in an
+     *             invalid format.
+     * @throws NoSuchProviderException
+     *             if no provider with the specified name can be found.
+     * @throws NoSuchPaddingException
+     *             if the requested padding scheme in the <i>transformation</i>
+     *             is not available.
+     * @throws IllegalArgumentException
+     *             if the specified provider is {@code null}.
      */
     public static final Cipher getInstance(String transformation,
             String provider) throws NoSuchAlgorithmException,
@@ -166,8 +219,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new cipher for the specified transformation.
+     *
+     * @param transformation
+     *            the name of the transformation to create a cipher for.
+     * @param provider
+     *            the provider to ask for the transformation.
+     * @return a cipher for the requested transformation.
+     * @throws NoSuchAlgorithmException
+     *             if the specified provider can not provide the
+     *             <i>transformation</i>, or it is {@code null}, empty or in an
+     *             invalid format.
+     * @throws NoSuchPaddingException
+     *             if the requested padding scheme in the <i>transformation</i>
+     *             is not available.
+     * @throws IllegalArgumentException
+     *             if the provider is {@code null}.
      */
     public static final Cipher getInstance(String transformation,
             Provider provider) throws NoSuchAlgorithmException,
@@ -223,9 +290,9 @@
                     }
                     break;
                 } catch (NoSuchAlgorithmException e) {
-                	if ( i == searhOrder.length-1) {
-                	    throw new NoSuchAlgorithmException(transformation);
-                	}
+                    if ( i == searhOrder.length-1) {
+                        throw new NoSuchAlgorithmException(transformation);
+                    }
                 }
             }
             switch (i) {
@@ -289,32 +356,44 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the provider of this cipher instance.
+     *
+     * @return the provider of this cipher instance.
      */
     public final Provider getProvider() {
         return provider;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the name of the algorithm of this cipher instance.
+     * <p>
+     * This is the name of the <i>transformation</i> argument used in the
+     * {@code getInstance} call creating this object.
+     *
+     * @return the name of the algorithm of this cipher instance.
      */
     public final String getAlgorithm() {
         return transformation;
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns this ciphers block size (in bytes).
+     *
+     * @return this ciphers block size.
      */
     public final int getBlockSize() {
         return spiImpl.engineGetBlockSize();
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the length in bytes an output buffer needs to be when this cipher
+     * is updated with {@code inputLen} bytes.
+     *
+     * @param inputLen
+     *            the number of bytes of the input.
+     * @return the output buffer length for the input length.
+     * @throws IllegalStateException
+     *             if this cipher instance is in an invalid state.
      */
     public final int getOutputSize(int inputLen) {
         if (mode == 0) {
@@ -325,24 +404,33 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the <i>initialization vector</i> for this cipher instance.
+     *
+     * @return the <i>initialization vector</i> for this cipher instance.
      */
     public final byte[] getIV() {
         return spiImpl.engineGetIV();
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the parameters that where used to create this cipher instance.
+     * <p>
+     * These may be a the same parameters that were used to create this cipher
+     * instance, or may be a combination of default and random parameters,
+     * depending on the underlying cipher implementation.
+     *
+     * @return the parameters that where used to create this cipher instance, or
+     *         {@code null} if this cipher instance does not have any
+     *         parameters.
      */
     public final AlgorithmParameters getParameters() {
         return spiImpl.engineGetParameters();
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the exemption mechanism associated with this cipher.
+     *
+     * @return currently {@code null}
      */
     public final ExemptionMechanism getExemptionMechanism() {
         //FIXME implement getExemptionMechanism
@@ -356,8 +444,31 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key.
+     * <p>
+     * The cipher is initialized for the specified operational mode (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * If this cipher instance needs any algorithm parameters or random values
+     * that the specified key can not provide, the underlying implementation of
+     * this cipher is supposed to generate the required parameters (using its
+     * provider or random values).
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, meaning that it
+     * is equivalent to creating a new instance and calling its {@code init}
+     * method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @throws InvalidKeyException
+     *             if the specified key can not be used to initialize this
+     *             cipher instance.
      */
     public final void init(int opmode, Key key) throws InvalidKeyException {
         if (sec_rand == null) {
@@ -370,8 +481,36 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key and a source of
+     * randomness.
+     * <p>
+     * The cipher is initialized for the specified operational mode (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * If this cipher instance needs any algorithm parameters or random values
+     * that the specified key can not provide, the underlying implementation of
+     * this cipher is supposed to generate the required parameters (using its
+     * provider or random values). Random values are generated using {@code
+     * random};
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, means it is
+     * equivalent to creating a new instance and calling it {@code init} method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @param random
+     *            the source of randomness to use.
+     * @throws InvalidKeyException
+     *             if the specified key can not be used to initialize this
+     *             cipher instance.
+     * @throws InvalidParameterException
+     *             if the specified opmode is invalid.
      */
     public final void init(int opmode, Key key, SecureRandom random)
             throws InvalidKeyException {
@@ -387,8 +526,35 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key and algorithm
+     * parameters.
+     * <p>
+     * The cipher is initialized for the specified operational mode (one of:
+     * encryption, decryption, key wrapping or key unwrapping).
+     * <p>
+     * If this cipher instance needs any algorithm parameters and {@code params}
+     * is {@code null}, the underlying implementation of this cipher is supposed
+     * to generate the required parameters (using its provider or random
+     * values).
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, means it is
+     * equivalent to creating a new instance and calling it {@code init} method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @param params
+     *            the algorithm parameters.
+     * @throws InvalidKeyException
+     *             if the specified key can not be used to initialize this
+     *             cipher instance.
+     * @throws InvalidAlgorithmParameterException
+     *             it the specified parameters are inappropriate for this
+     *             cipher.
      */
     public final void init(int opmode, Key key, AlgorithmParameterSpec params)
             throws InvalidKeyException, InvalidAlgorithmParameterException {
@@ -399,8 +565,41 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key, algorithm
+     * parameters and a source of randomness.
+     * <p>
+     * The cipher is initialized for the specified operational mode (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * If this cipher instance needs any algorithm parameters and {@code params}
+     * is {@code null}, the underlying implementation of this cipher is supposed
+     * to generate the required parameters (using its provider or random
+     * values). Random values are generated using {@code random};
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, meaning that it
+     * is equivalent to creating a new instance and calling it {@code init}
+     * method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @param params
+     *            the algorithm parameters.
+     * @param random
+     *            the source of randomness to use.
+     * @throws InvalidKeyException
+     *             if the specified key can not be used to initialize this
+     *             cipher instance.
+     * @throws InvalidAlgorithmParameterException
+     *             it the specified parameters are inappropriate for this
+     *             cipher.
+     * @throws InvalidParameterException
+     *             if the specified {@code opmode} is invalid.
      */
     public final void init(int opmode, Key key, AlgorithmParameterSpec params,
             SecureRandom random) throws InvalidKeyException,
@@ -420,8 +619,37 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key and algorithm
+     * parameters.
+     * <p>
+     * The cipher is initialized for the specified operation (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * If this cipher instance needs any algorithm parameters and {@code params}
+     * is {@code null}, the underlying implementation of this cipher is supposed
+     * to generate the required parameters (using its provider or random
+     * values).
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, meaning that it
+     * is equivalent to creating a new instance and calling it {@code init}
+     * method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @param params
+     *            the algorithm parameters.
+     * @throws InvalidKeyException
+     *             if the specified key can not be used to initialize this
+     *             cipher instance.
+     * @throws InvalidAlgorithmParameterException
+     *             it the specified parameters are inappropriate for this
+     *             cipher.
      */
     public final void init(int opmode, Key key, AlgorithmParameters params)
             throws InvalidKeyException, InvalidAlgorithmParameterException {
@@ -432,8 +660,40 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key, algorithm
+     * parameters and a source of randomness.
+     * <p>
+     * The cipher will be initialized for the specified operation (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * If this cipher instance needs any algorithm parameters and {@code params}
+     * is {@code null}, the underlying implementation of this cipher is supposed
+     * to generate the required parameters (using its provider or random
+     * values). Random values are generated using {@code random}.
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, means it is
+     * equivalent to creating a new instance and calling it {@code init} method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @param params
+     *            the algorithm parameters.
+     * @param random
+     *            the source of randomness to use.
+     * @throws InvalidKeyException
+     *             if the specified key can not be used to initialize this
+     *             cipher instance.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters are inappropriate for this
+     *             cipher.
+     * @throws InvalidParameterException
+     *             if the specified {@code opmode} is invalid.
      */
     public final void init(int opmode, Key key, AlgorithmParameters params,
             SecureRandom random) throws InvalidKeyException,
@@ -453,8 +713,36 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the public key from the specified
+     * certificate.
+     * <p>
+     * The cipher will be initialized for the specified operation (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * It the type of the certificate is X.509 and the certificate has a <i>key
+     * usage</i> extension field marked as critical, the specified {@code
+     * opmode} has the be enabled for this key, otherwise an {@code
+     * InvalidKeyException} is thrown.
+     * <p>
+     * If this cipher instance needs any algorithm parameters that the key in
+     * the certificate can not provide, the underlying implementation of this
+     * cipher is supposed to generate the required parameters (using its
+     * provider or random values).
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, means it is
+     * equivalent to creating a new instance and calling it {@code init} method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param certificate
+     *            the certificate.
+     * @throws InvalidKeyException
+     *             if the public key in the certificate can not be used to
+     *             initialize this cipher instance.
      */
     public final void init(int opmode, Certificate certificate)
             throws InvalidKeyException {
@@ -465,8 +753,39 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the public key from the specified
+     * certificate and a source of randomness.
+     * <p>
+     * The cipher will be initialized for the specified operation (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * It the type of the certificate is X.509 and the certificate has a <i>key
+     * usage</i> extension field marked as critical, the specified {@code
+     * opmode} has the be enabled for this key, otherwise an {@code
+     * InvalidKeyException} is thrown.
+     * <p>
+     * If this cipher instance needs any algorithm parameters that the key in
+     * the certificate can not provide, the underlying implementation of this
+     * cipher is supposed to generate the required parameters (using its
+     * provider or random values). Random values are generated using {@code
+     * random}.
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, means it is
+     * equivalent to creating a new instance and calling it {@code init} method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param certificate
+     *            the certificate.
+     * @param random
+     *            the source of randomness to be used.
+     * @throws InvalidKeyException
+     *             if the public key in the certificate can not be used to
+     *             initialize this cipher instance.
      */
     public final void init(int opmode, Certificate certificate,
             SecureRandom random) throws InvalidKeyException {
@@ -516,8 +835,18 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Continues a multi-part transformation (encryption or decryption). The
+     * transformed bytes are returned.
+     *
+     * @param input
+     *            the input bytes to transform.
+     * @return the transformed bytes in a new buffer, or {@code null} if the
+     *         input has zero length.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if the input is {@code null}.
      */
     public final byte[] update(byte[] input) {
         if (mode != ENCRYPT_MODE && mode != DECRYPT_MODE) {
@@ -534,8 +863,24 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Continues a multi-part transformation (encryption or decryption). The
+     * transformed bytes are returned.
+     *
+     * @param input
+     *            the input bytes to transform.
+     * @param inputOffset
+     *            the offset in the input to start.
+     * @param inputLen
+     *            the length of the input to transform.
+     * @return the transformed bytes in a new buffer, or {@code null} if the
+     *         input has zero length.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if the input is {@code null}, or if {@code inputOffset} and
+     *             {@code inputLen} do not specify a valid chunk in the input
+     *             buffer.
      */
     public final byte[] update(byte[] input, int inputOffset, int inputLen) {
         if (mode != ENCRYPT_MODE && mode != DECRYPT_MODE) {
@@ -558,8 +903,32 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Continues a multi-part transformation (encryption or decryption). The
+     * transformed bytes are stored in the {@code output} buffer.
+     * <p>
+     * If the size of the {@code output} buffer is too small to hold the result,
+     * a {@code ShortBufferException} is thrown. Use
+     * {@link Cipher#getOutputSize getOutputSize} to check for the size of the
+     * output buffer.
+     *
+     * @param input
+     *            the input bytes to transform.
+     * @param inputOffset
+     *            the offset in the input to start.
+     * @param inputLen
+     *            the length of the input to transform.
+     * @param output
+     *            the output buffer.
+     * @return the number of bytes placed in output.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if the input is {@code null}, the output is {@code null}, or
+     *             if {@code inputOffset} and {@code inputLen} do not specify a
+     *             valid chunk in the input buffer.
      */
     public final int update(byte[] input, int inputOffset, int inputLen,
             byte[] output) throws ShortBufferException {
@@ -567,8 +936,34 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Continues a multi-part transformation (encryption or decryption). The
+     * transformed bytes are stored in the {@code output} buffer.
+     * <p>
+     * If the size of the {@code output} buffer is too small to hold the result,
+     * a {@code ShortBufferException} is thrown. Use
+     * {@link Cipher#getOutputSize getOutputSize} to check for the size of the
+     * output buffer.
+     *
+     * @param input
+     *            the input bytes to transform.
+     * @param inputOffset
+     *            the offset in the input to start.
+     * @param inputLen
+     *            the length of the input to transform.
+     * @param output
+     *            the output buffer.
+     * @param outputOffset
+     *            the offset in the output buffer.
+     * @return the number of bytes placed in output.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if the input is {@code null}, the output is {@code null}, or
+     *             if {@code inputOffset} and {@code inputLen} do not specify a
+     *             valid chunk in the input buffer.
      */
     public final int update(byte[] input, int inputOffset, int inputLen,
             byte[] output, int outputOffset) throws ShortBufferException {
@@ -600,8 +995,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Continues a multi-part transformation (encryption or decryption). The
+     * {@code input.remaining()} bytes starting at {@code input.position()} are
+     * transformed and stored in the {@code output} buffer.
+     * <p>
+     * If the {@code output.remaining()} is too small to hold the transformed
+     * bytes a {@code ShortBufferException} is thrown. Use
+     * {@link Cipher#getOutputSize getOutputSize} to check for the size of the
+     * output buffer.
+     *
+     * @param input
+     *            the input buffer to transform.
+     * @param output
+     *            the output buffer to store the result within.
+     * @return the number of bytes stored in the output buffer.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if the input buffer and the output buffer are the identical
+     *             object.
      */
     public final int update(ByteBuffer input, ByteBuffer output)
             throws ShortBufferException {
@@ -617,8 +1032,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes any bytes that may have been buffered in previous {@code
+     * update} calls.
+     *
+     * @return the final bytes from the transformation.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
      */
     public final byte[] doFinal() throws IllegalBlockSizeException,
             BadPaddingException {
@@ -630,8 +1057,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes any bytes that may have been buffered in previous {@code
+     * update} calls.
+     * <p>
+     * The final transformed bytes are stored in the {@code output} buffer.
+     *
+     * @param output
+     *            the output buffer.
+     * @param outputOffset
+     *            the offset in the output buffer.
+     * @return the number of bytes placed in the output buffer.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
      */
     public final int doFinal(byte[] output, int outputOffset)
             throws IllegalBlockSizeException, ShortBufferException,
@@ -648,8 +1095,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes the bytes in {@code input} buffer, and any bytes that have been
+     * buffered in previous {@code update} calls.
+     *
+     * @param input
+     *            the input buffer.
+     * @return the final bytes from the transformation.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
      */
     public final byte[] doFinal(byte[] input) throws IllegalBlockSizeException,
             BadPaddingException {
@@ -661,8 +1122,30 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes the {@code inputLen} bytes in {@code input} buffer at {@code
+     * inputOffset}, and any bytes that have been buffered in previous {@code
+     * update} calls.
+     *
+     * @param input
+     *            the input buffer.
+     * @param inputOffset
+     *            the offset in the input buffer.
+     * @param inputLen
+     *            the length of the input
+     * @return the final bytes from the transformation.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if {@code inputOffset} and {@code inputLen} do not specify an
+     *             valid chunk in the input buffer.
      */
     public final byte[] doFinal(byte[] input, int inputOffset, int inputLen)
             throws IllegalBlockSizeException, BadPaddingException {
@@ -679,8 +1162,34 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes the {@code inputLen} bytes in {@code input} buffer at {@code
+     * inputOffset}, and any bytes that have been buffered in previous {@code
+     * update} calls.
+     *
+     * @param input
+     *            the input buffer.
+     * @param inputOffset
+     *            the offset in the input buffer.
+     * @param inputLen
+     *            the length of the input.
+     * @param output
+     *            the output buffer for the transformed bytes.
+     * @return the number of bytes placed in the output buffer.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if {@code inputOffset} and {@code inputLen} do not specify an
+     *             valid chunk in the input buffer.
      */
     public final int doFinal(byte[] input, int inputOffset, int inputLen,
             byte[] output) throws ShortBufferException,
@@ -689,8 +1198,36 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes the {@code inputLen} bytes in {@code input} buffer at {@code
+     * inputOffset}, and any bytes that have been buffered in previous {@code
+     * update} calls.
+     *
+     * @param input
+     *            the input buffer.
+     * @param inputOffset
+     *            the offset in the input buffer.
+     * @param inputLen
+     *            the length of the input.
+     * @param output
+     *            the output buffer for the transformed bytes.
+     * @param outputOffset
+     *            the offset in the output buffer.
+     * @return the number of bytes placed in the output buffer.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if {@code inputOffset} and {@code inputLen} do not specify an
+     *             valid chunk in the input buffer.
      */
     public final int doFinal(byte[] input, int inputOffset, int inputLen,
             byte[] output, int outputOffset) throws ShortBufferException,
@@ -709,8 +1246,31 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes the {@code input.remaining()} bytes in {@code input} buffer at
+     * {@code input.position()}, and any bytes that have been buffered in
+     * previous {@code update} calls. The transformed bytes are placed into
+     * {@code output} buffer.
+     *
+     * @param input
+     *            the input buffer.
+     * @param output
+     *            the output buffer.
+     * @return the number of bytes placed into the output buffer.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
+     * @throws IllegalArgumentException
+     *             if the input buffer and the output buffer are the same
+     *             object.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
      */
     public final int doFinal(ByteBuffer input, ByteBuffer output)
             throws ShortBufferException, IllegalBlockSizeException,
@@ -727,8 +1287,18 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Wraps a key using this cipher instance.
+     *
+     * @param key
+     *            the key to wrap.
+     * @return the wrapped key.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws InvalidKeyException
+     *             if this cipher instance can not wrap this key.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for wrapping.
      */
     public final byte[] wrap(Key key) throws IllegalBlockSizeException,
             InvalidKeyException {
@@ -740,8 +1310,25 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Unwraps a key using this cipher instance.
+     *
+     * @param wrappedKey
+     *            the wrapped key to unwrap.
+     * @param wrappedKeyAlgorithm
+     *            the algorithm for the wrapped key.
+     * @param wrappedKeyType
+     *            the type of the wrapped key (one of: {@code SECRET_KEY
+     *            <code>, <code>PRIVATE_KEY} or {@code PUBLIC_KEY})
+     * @return the unwrapped key
+     * @throws InvalidKeyException
+     *             if the {@code wrappedKey} can not be unwrapped to a key of
+     *             type {@code wrappedKeyType} for the {@code
+     *             wrappedKeyAlgorithm}.
+     * @throws NoSuchAlgorithmException
+     *             if no provider can be found that can create a key of type
+     *             {@code wrappedKeyType} for the {@code wrappedKeyAlgorithm}.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for unwrapping.
      */
     public final Key unwrap(byte[] wrappedKey, String wrappedKeyAlgorithm,
             int wrappedKeyType) throws InvalidKeyException,
@@ -755,8 +1342,16 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the maximum key length for the specified transformation.
+     *
+     * @param transformation
+     *            the transformation name.
+     * @return the maximum key length, currently {@code Integer.MAX_VALUE}.
+     * @throws NoSuchAlgorithmException
+     *             if no provider for the specified {@code transformation} can
+     *             be found.
+     * @throws NullPointerException
+     *             if {@code transformation} is {@code null}.
      */
     public static final int getMaxAllowedKeyLength(String transformation)
             throws NoSuchAlgorithmException {
@@ -769,8 +1364,18 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the maximum cipher parameter value for the specified
+     * transformation. If there is no maximum limit, {@code null} is returned.
+     *
+     * @param transformation
+     *            the transformation name.
+     * @return a parameter spec holding the maximum value or {@code null}.
+     *         Currently {@code null}.
+     * @throws NoSuchAlgorithmException
+     *             if no provider for the specified {@code transformation} can
+     *             be found.
+     * @throws NullPointerException
+     *             if {@code transformation} is {@code null}.
      */
     public static final AlgorithmParameterSpec getMaxAllowedParameterSpec(
             String transformation) throws NoSuchAlgorithmException {

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java Sun Apr 26 12:30:01 2009
@@ -29,7 +29,14 @@
 import java.security.GeneralSecurityException;
 
 /**
- * @com.intel.drl.spec_ref
+ * This class wraps an {@code InputStream} and a cipher so that {@code read()}
+ * methods return data that are read from the underlying {@code InputStream} and
+ * processed by the cipher.
+ * <p>
+ * The cipher must be initialized for the requested operation before being used
+ * by a {@code CipherInputStream}. For example, if a cipher initialized for
+ * decryption is used with a {@code CipherInputStream}, the {@code
+ * CipherInputStream} tries to read the data an decrypt them before returning.
  */
 public class CipherInputStream extends FilterInputStream {
 
@@ -41,7 +48,13 @@
     private boolean finished;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CipherInputStream} instance for an {@code
+     * InputStream} and a cipher.
+     *
+     * @param is
+     *            the input stream to read data from.
+     * @param c
+     *            the cipher to process the data with.
      */
     public CipherInputStream(InputStream is, Cipher c) {
         super(is);
@@ -49,14 +62,24 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CipherInputStream} instance for an {@code
+     * InputStream} without a cipher.
+     * <p>
+     * A {@code NullCipher} is created and used to process the data.
+     *
+     * @param is
+     *            the input stream to read data from.
      */
     protected CipherInputStream(InputStream is) {
         this(is, new NullCipher());
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Reads the next byte from this cipher input stream.
+     *
+     * @return the next byte, or {@code -1} if the end of the stream is reached.
+     * @throws IOException
+     *             if an error occurs.
      */
     @Override
     public int read() throws IOException {
@@ -87,7 +110,15 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Reads the next {@code b.length} bytes from this input stream into buffer
+     * {@code b}.
+     *
+     * @param b
+     *            the buffer to be filled with data.
+     * @return the number of bytes filled into buffer {@code b}, or {@code -1}
+     *         if the end of the stream is reached.
+     * @throws IOException
+     *             if an error occurs.
      */
     @Override
     public int read(byte[] b) throws IOException {
@@ -95,7 +126,24 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Reads the next {@code len} bytes from this input stream into buffer
+     * {@code b} starting at offset {@code off}.
+     * <p>
+     * if {@code b} is {@code null}, the next {@code len} bytes are read and
+     * discarded.
+     *
+     * @param b
+     *            the buffer to be filled with data.
+     * @param off
+     *            the offset to start in the buffer.
+     * @param len
+     *            the maximum number of bytes to read.
+     * @return the number of bytes filled into buffer {@code b}, or {@code -1}
+     *         of the of the stream is reached.
+     * @throws IOException
+     *             if an error occurs.
+     * @throws NullPointerException
+     *             if the underlying input stream is {@code null}.
      */
     @Override
     public int read(byte[] b, int off, int len) throws IOException {
@@ -117,7 +165,17 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Skips up to n bytes from this input stream.
+     * <p>
+     * The number of bytes skipped depends on the result of a call to
+     * {@link CipherInputStream#available() available}. The smaller of n and the
+     * result are the number of bytes being skipped.
+     *
+     * @param n
+     *            the number of bytes that should be skipped.
+     * @return the number of bytes actually skipped.
+     * @throws IOException
+     *             if an error occurs
      */
     @Override
     public long skip(long n) throws IOException {
@@ -133,7 +191,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the number of bytes available without blocking.
+     *
+     * @return the number of bytes available, currently zero.
+     * @throws IOException
+     *             if an error occurs
      */
     @Override
     public int available() throws IOException {
@@ -141,7 +203,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Closes this {@code CipherInputStream}, also closes the underlying input
+     * stream and call {@code doFinal} on the cipher object.
+     *
+     * @throws IOException
+     *             if an error occurs.
      */
     @Override
     public void close() throws IOException {
@@ -155,7 +221,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns whether this input stream supports {@code mark} and
+     * {@code reset}, which it does not.
+     *
+     * @return false, since this input stream does not support {@code mark} and
+     *         {@code reset}.
      */
     @Override
     public boolean markSupported() {

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java Sun Apr 26 12:30:01 2009
@@ -28,7 +28,14 @@
 import javax.crypto.NullCipher;
 
 /**
- * @com.intel.drl.spec_ref
+ * This class wraps an output stream and a cipher so that {@code write} methods
+ * send the data through the cipher before writing them to the underlying output
+ * stream.
+ * <p>
+ * The cipher must be initialized for the requested operation before being used
+ * by a {@code CipherOutputStream}. For example, if a cipher initialized for
+ * encryption is used with a {@code CipherOutputStream}, the {@code
+ * CipherOutputStream} tries to encrypt the data writing it out.
  */
 public class CipherOutputStream extends FilterOutputStream {
 
@@ -36,7 +43,13 @@
     private final byte[] arr = new byte[1];
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CipherOutputStream} instance for an {@code
+     * OutputStream} and a {@code Cipher}.
+     *
+     * @param os
+     *            the output stream to write data to.
+     * @param c
+     *            the cipher to process the data with.
      */
     public CipherOutputStream(OutputStream os, Cipher c) {
         super(os);
@@ -44,14 +57,25 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates a new {@code CipherOutputStream} instance for an {@code
+     * OutputStream} without a cipher.
+     * <p>
+     * A {@code NullCipher} is created to process the data.
+     *
+     * @param os
+     *            the output stream to write the data to.
      */
     protected CipherOutputStream(OutputStream os) {
         this(os, new NullCipher());
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Writes the single byte to this cipher output stream.
+     *
+     * @param b
+     *            the byte to write.
+     * @throws IOException
+     *             if an error occurs.
      */
     @Override
     public void write(int b) throws IOException {
@@ -64,7 +88,12 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Writes the buffer of bytes to this cipher output stream.
+     *
+     * @param b
+     *            the buffer of bytes.
+     * @throws IOException
+     *             if an error occurs.
      */
     @Override
     public void write(byte[] b) throws IOException {
@@ -72,7 +101,17 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Writes the {@code len} bytes from buffer {@code b} starting at offset
+     * {@code off} to this cipher output stream.
+     *
+     * @param b
+     *            the buffer.
+     * @param off
+     *            the offset to start at.
+     * @param len
+     *            the number of bytes.
+     * @throws IOException
+     *             if an error occurs.
      */
     @Override
     public void write(byte[] b, int off, int len) throws IOException {
@@ -86,7 +125,10 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Flushes this cipher output stream.
+     *
+     * @throws IOException
+     *             if an error occurs
      */
     @Override
     public void flush() throws IOException {
@@ -94,7 +136,14 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Close this cipher output stream.
+     * <p>
+     * On the underlying cipher {@code doFinal} will be invoked, and any
+     * buffered bytes from the cipher are also written out, and the cipher is
+     * reset to its initial state. The underlying output stream is also closed.
+     *
+     * @throws IOException
+     *             if an error occurs.
      */
     @Override
     public void close() throws IOException {

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherSpi.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherSpi.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/CipherSpi.java Sun Apr 26 12:30:01 2009
@@ -34,98 +34,306 @@
 import org.apache.harmony.crypto.internal.nls.Messages;
 
 /**
- * @com.intel.drl.spec_ref
- * 
+ * This class defines the <i>Service Provider Interface</i> (<b>SPI</b>) for
+ * cryptographic ciphers.
+ * <p>
+ * Implementers of cryptographic ciphers must implement all the abstract methods
+ * for every cipher they implement. {@code CipherSpi} instances are created
+ * along with ciphers when the {@link Cipher#getInstance} method is called. A
+ * {@code Cipher} is referenced by a <i>transformation</i>, which is a string
+ * that describes the operation (or set of operations), always consisting of the
+ * cipher's name and optionally followed by a mode and a padding, in the form:
+ * <ul>
+ * <li>"algorithm"</li>or
+ * <li>"algorithm/mode/padding"</li>
+ * </ul>
+ * The following behavior should be implemented for obtaining {@code Cipher}
+ * instances.
+ * <p>
+ * When one of the {@link Cipher#getInstance} factory methods is called with a
+ * <i>transformation</i> that is only an <i>algorithm</i>, check if the provider
+ * defines a {@code CipherSpi} for "algorithm", if so: return it, otherwise
+ * throw a {@link NoSuchAlgorithmException}.
+ * <p>
+ * The following rules apply when a <i>transformation</i> is of the form
+ * "algorithm/mode/padding":
+ * <ul>
+ * 1. The Provider has a {@code CipherSpi} subclass registered for
+ * "algorithm/mode/padding": return it, otherwise go to step 2.
+ * </ul>
+ * <ul>
+ * 2. The Provider has a {@code CipherSpi} subclass registered for
+ * "algorithm/mode": instantiate it, call
+ * {@link CipherSpi#engineSetPadding(String) engineSetPadding(String)} for the
+ * padding name and return it, otherwise go to step 3.
+ * </ul>
+ * <ul>
+ * 3. The Provider has a {@code CipherSpi} subclass registered for
+ * "algorithm//padding": instantiate it, call
+ * {@link CipherSpi#engineSetMode(String) engineSetMode(String)} for the mode
+ * name and return it, otherwise go to step 4.
+ * </ul>
+ * <ul>
+ * 4. The Provider has a {@code CipherSpi} subclass registered for "algorithm":
+ * instantiate it, call {@link CipherSpi#engineSetMode(String)
+ * engineSetMode(String)} for the mode name , call
+ * {@link CipherSpi#engineSetPadding(String) engineSetPadding(String)} for the
+ * padding name and return it, otherwise throw a
+ * {@link NoSuchAlgorithmException}.
+ * </ul>
+ *
+ * @see Cipher
  */
-
 public abstract class CipherSpi {
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Creates a new {@code CipherSpi} instance.
      */
     public CipherSpi() {
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Sets the mode for this cipher.
+     *
+     * @param mode
+     *            the name of the cipher mode.
+     * @throws NoSuchAlgorithmException
+     *             if the specified cipher mode is not supported by this
+     *             provider.
      */
     protected abstract void engineSetMode(String mode)
             throws NoSuchAlgorithmException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Sets the padding method for this cipher.
+     *
+     * @param padding
+     *            the name of the padding method.
+     * @throws NoSuchPaddingException
+     *             if the specified padding method is not supported by this
+     *             cipher.
      */
     protected abstract void engineSetPadding(String padding)
             throws NoSuchPaddingException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the block size of this cipher (in bytes)
+     *
+     * @return the block size of this cipher, or zero if this cipher is not a
+     *         block cipher.
      */
     protected abstract int engineGetBlockSize();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the size for a buffer (in bytes), that the next call to {@code
+     * update} of {@code doFinal} would return, taking into account any buffered
+     * data from previous {@code update} calls and padding.
+     * <p>
+     * The actual output length of the next call to {@code update} or {@code
+     * doFinal} may be smaller than the length returned by this method.
+     *
+     * @param inputLen
+     *            the length of the input (in bytes).
+     * @return the size for a buffer (in bytes).
      */
     protected abstract int engineGetOutputSize(int inputLen);
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the Initialization Vector (IV) that was used to initialize this
+     * cipher or {@code null} if none was used.
+     *
+     * @return the Initialization Vector (IV), or {@code null} if none was used.
      */
     protected abstract byte[] engineGetIV();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the parameters that where used to create this cipher instance.
+     * <p>
+     * These may be a the same parameters that were used to create this cipher
+     * instance, or may be a combination of default and random parameters,
+     * depending on the underlying cipher implementation.
+     *
+     * @return the parameters that where used to create this cipher instance, or
+     *         {@code null} if this cipher instance does not have any parameters
+     *         at all.
      */
     protected abstract AlgorithmParameters engineGetParameters();
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key and a source of
+     * randomness.
+     * <p>
+     * The cipher will be initialized for the specified operation (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * If this cipher instance needs any algorithm parameters or random values
+     * that the specified key cannot provide, the underlying implementation of
+     * this cipher is supposed to generate the required parameters (using its
+     * provider or random values). Random values will be generated using {@code
+     * random};
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, means it is
+     * equivalent to creating a new instance and calling it {@code init} method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @param random
+     *            the source of randomness to use.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this cipher
+     *             instance.
      */
     protected abstract void engineInit(int opmode, Key key, SecureRandom random)
             throws InvalidKeyException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key, algorithm
+     * parameters and a source of randomness.
+     * <p>
+     * The cipher will be initialized for the specified operation (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * If this cipher instance needs any algorithm parameters and {@code params}
+     * is {@code null}, the underlying implementation of this cipher is supposed
+     * to generate the required parameters (using its provider or random
+     * values). Random values are generated using {@code random}.
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, means it is
+     * equivalent to creating a new instance and calling it {@code init} method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @param params
+     *            the algorithm parameters.
+     * @param random
+     *            the source of randomness to use.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this cipher
+     *             instance.
+     * @throws InvalidAlgorithmParameterException
+     *             it the specified parameters are inappropriate for this
+     *             cipher.
      */
     protected abstract void engineInit(int opmode, Key key,
             AlgorithmParameterSpec params, SecureRandom random)
             throws InvalidKeyException, InvalidAlgorithmParameterException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Initializes this cipher instance with the specified key, algorithm
+     * parameters and a source of randomness.
+     * <p>
+     * The cipher will be initialized for the specified operation (one of:
+     * encryption, decryption, key wrapping or key unwrapping) depending on
+     * {@code opmode}.
+     * <p>
+     * If this cipher instance needs any algorithm parameters and {@code params}
+     * is {@code null}, the underlying implementation of this cipher is supposed
+     * to generate the required parameters (using its provider or random
+     * values). Random values are generated using {@code random}.
+     * <p>
+     * When a cipher instance is initialized by a call to any of the {@code
+     * init} methods, the state of the instance is overridden, means it is
+     * equivalent to creating a new instance and calling it {@code init} method.
+     *
+     * @param opmode
+     *            the operation this cipher instance should be initialized for
+     *            (one of: {@code ENCRYPT_MODE}, {@code DECRYPT_MODE}, {@code
+     *            WRAP_MODE} or {@code UNWRAP_MODE}).
+     * @param key
+     *            the input key for the operation.
+     * @param params
+     *            the algorithm parameters.
+     * @param random
+     *            the source of randomness to use.
+     * @throws InvalidKeyException
+     *             if the specified key cannot be used to initialize this cipher
+     *             instance.
+     * @throws InvalidAlgorithmParameterException
+     *             if the specified parameters are inappropriate for this
+     *             cipher.
      */
     protected abstract void engineInit(int opmode, Key key,
             AlgorithmParameters params, SecureRandom random)
             throws InvalidKeyException, InvalidAlgorithmParameterException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Continues a multi-part transformation (encryption or decryption). The
+     * transformed bytes are returned.
+     *
+     * @param input
+     *            the input bytes to transform.
+     * @param inputOffset
+     *            the offset in the input to start.
+     * @param inputLen
+     *            the length of the input to transform.
+     * @return the transformed bytes in a new buffer, or {@code null} if the
+     *         input has zero length.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
+     * @throws IllegalArgumentException
+     *             if the input is null, or if {@code inputOffset} and {@code
+     *             inputLen} do not specify a valid chunk in the input buffer.
      */
     protected abstract byte[] engineUpdate(byte[] input, int inputOffset,
             int inputLen);
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Continues a multi-part transformation (encryption or decryption). The
+     * transformed bytes are stored in the {@code output} buffer.
+     * <p>
+     * If the size of the {@code output} buffer is too small to hold the result,
+     * a {@code ShortBufferException} is thrown. Use
+     * {@link Cipher#getOutputSize getOutputSize} to check for the size of the
+     * output buffer.
+     *
+     * @param input
+     *            the input bytes to transform.
+     * @param inputOffset
+     *            the offset in the input to start.
+     * @param inputLen
+     *            the length of the input to transform.
+     * @param output
+     *            the output buffer.
+     * @param outputOffset
+     *            the offset in the output buffer.
+     * @return the number of bytes placed in output.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
      */
     protected abstract int engineUpdate(byte[] input, int inputOffset,
             int inputLen, byte[] output, int outputOffset)
             throws ShortBufferException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Continues a multi-part transformation (encryption or decryption). The
+     * {@code input.remaining()} bytes starting at {@code input.position()} are
+     * transformed and stored in the {@code output} buffer.
+     * <p>
+     * If the {@code output.remaining()} is too small to hold the transformed
+     * bytes a {@code ShortBufferException} is thrown. Use
+     * {@link Cipher#getOutputSize getOutputSize} to check for the size of the
+     * output buffer.
+     *
+     * @param input
+     *            the input buffer to transform.
+     * @param output
+     *            the output buffer to store the result within.
+     * @return the number of bytes stored in the output buffer.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
      */
     protected int engineUpdate(ByteBuffer input, ByteBuffer output)
             throws ShortBufferException {
@@ -164,15 +372,53 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes the {@code inputLen} bytes in {@code input} buffer at {@code
+     * inputOffset}, and any bytes that have been buffered in previous {@code
+     * update} calls.
+     *
+     * @param input
+     *            the input buffer.
+     * @param inputOffset
+     *            the offset in the input buffer.
+     * @param inputLen
+     *            the length of the input.
+     * @return the final bytes from the transformation.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
      */
     protected abstract byte[] engineDoFinal(byte[] input, int inputOffset,
             int inputLen) throws IllegalBlockSizeException, BadPaddingException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes the {@code inputLen} bytes in {@code input} buffer at
+     * {@code inputOffset}, and any bytes that have been buffered in previous
+     * {@code update} calls.
+     *
+     * @param input
+     *            the input buffer.
+     * @param inputOffset
+     *            the offset in the input buffer.
+     * @param inputLen
+     *            the length of the input.
+     * @param output
+     *            the output buffer for the transformed bytes.
+     * @param outputOffset
+     *            the offset in the output buffer.
+     * @return the number of bytes placed in the output buffer.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
      */
     protected abstract int engineDoFinal(byte[] input, int inputOffset,
             int inputLen, byte[] output, int outputOffset)
@@ -180,8 +426,31 @@
             BadPaddingException;
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Finishes a multi-part transformation (encryption or decryption).
+     * <p>
+     * Processes the {@code input.remaining()} bytes in {@code input} buffer at
+     * {@code input.position()}, and any bytes that have been buffered in
+     * previous {@code update} calls. The transformed bytes are placed into
+     * {@code output} buffer.
+     *
+     * @param input
+     *            the input buffer.
+     * @param output
+     *            the output buffer.
+     * @return the number of bytes placed into the output buffer.
+     * @throws ShortBufferException
+     *             if the size of the {@code output} buffer is too small.
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws BadPaddingException
+     *             if the padding of the data does not match the padding scheme.
+     * @throws IllegalArgumentException
+     *             if the input buffer and the output buffer are the same
+     *             object.
+     * @throws IllegalStateException
+     *             if this cipher instance is not initialized for encryption or
+     *             decryption.
      */
     protected int engineDoFinal(ByteBuffer input, ByteBuffer output)
             throws ShortBufferException, IllegalBlockSizeException,
@@ -223,8 +492,19 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Wraps a key using this cipher instance. This method has been added to
+     * this class (for backwards compatibility, it cannot be abstract). If this
+     * method is not overridden, it throws an {@code
+     * UnsupportedOperationException}.
+     *
+     * @param key
+     *            the key to wrap.
+     * @return the wrapped key
+     * @throws IllegalBlockSizeException
+     *             if the size of the resulting bytes is not a multiple of the
+     *             cipher block size.
+     * @throws InvalidKeyException
+     *             if this cipher instance cannot wrap this key.
      */
     protected byte[] engineWrap(Key key) throws IllegalBlockSizeException,
             InvalidKeyException {
@@ -233,8 +513,27 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Unwraps a key using this cipher instance.
+     * <p>
+     * This method has been added to this class (for backwards compatibility, it
+     * cannot be abstract). If this method is not overridden, it throws an
+     * {@code UnsupportedOperationException}.
+     *
+     * @param wrappedKey
+     *            the wrapped key to unwrap.
+     * @param wrappedKeyAlgorithm
+     *            the algorithm for the wrapped key.
+     * @param wrappedKeyType
+     *            the type of the wrapped key (one of: {@code SECRET_KEY},
+     *            {@code PRIVATE_KEY} or {@code PUBLIC_KEY})
+     * @return the unwrapped key.
+     * @throws InvalidKeyException
+     *             if the {@code wrappedKey} cannot be unwrapped to a key of
+     *             type {@code wrappedKeyType} for the {@code
+     *             wrappedKeyAlgorithm}.
+     * @throws NoSuchAlgorithmException
+     *             if no provider can be found that can create a key of type
+     *             {@code wrappedKeyType} for the {@code wrappedKeyAlgorithm}.
      */
     protected Key engineUnwrap(byte[] wrappedKey, String wrappedKeyAlgorithm,
             int wrappedKeyType) throws InvalidKeyException,
@@ -244,8 +543,17 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
-     *  
+     * Returns the size of a specified key object in bits. This method has been
+     * added to this class (for backwards compatibility, it cannot be abstract).
+     * If this method is not overridden, it throws an {@code
+     * UnsupportedOperationException}.
+     *
+     * @param key
+     *            the key to get the size for.
+     * @return the size of a specified key object in bits.
+     * @throws InvalidKeyException
+     *             if the size of the key cannot be determined by this
+     *             implementation.
      */
     protected int engineGetKeySize(Key key) throws InvalidKeyException {
         throw new UnsupportedOperationException(

Modified: harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java Sun Apr 26 12:30:01 2009
@@ -46,7 +46,21 @@
 
 
 /**
- * @com.intel.drl.spec_ref
+ * This class implements the {@code EncryptedPrivateKeyInfo} ASN.1 type as
+ * specified in <a href="http://www.ietf.org/rfc/rfc5208.txt">PKCS
+ * #8 - Private-Key Information Syntax Standard</a>.
+ * <p>
+ * The definition of ASN.1 is as follows:
+ * <dl>
+ * EncryptedPrivateKeyInfo ::= SEQUENCE {
+ * <dd>encryptionAlgorithm AlgorithmIdentifier,</dd>
+ * <dd>encryptedData OCTET STRING }</dd>
+ * </dl>
+ * <dl>
+ * AlgorithmIdentifier ::= SEQUENCE {
+ * <dd>algorithm OBJECT IDENTIFIER,</dd>
+ * <dd>parameters ANY DEFINED BY algorithm OPTIONAL }</dd>
+ * </dl>
  */
 public class EncryptedPrivateKeyInfo {
     // Encryption algorithm name
@@ -61,7 +75,15 @@
     private volatile byte[] encoded;
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates an {@code EncryptedPrivateKeyInfo} instance from its encoded
+     * representation by parsing it.
+     *
+     * @param encoded
+     *            the encoded representation of this object
+     * @throws IOException
+     *             if parsing the encoded representation fails.
+     * @throws NullPointerException
+     *             if {@code encoded} is {@code null}.
      */
     public EncryptedPrivateKeyInfo(byte[] encoded)
             throws IOException {
@@ -104,7 +126,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates an {@code EncryptedPrivateKeyInfo} instance from an algorithm
+     * name and its encrypted data.
+     *
+     * @param encrAlgName
+     *            the name of an algorithm.
+     * @param encryptedData
+     *            the encrypted data.
+     * @throws NoSuchAlgorithmException
+     *             if the {@code encrAlgName} is not a supported algorithm.
+     * @throws NullPointerException
+     *             if {@code encrAlgName} or {@code encryptedData} is {@code
+     *             null}.
+     * @throws IllegalArgumentException
+     *             if {@code encryptedData} is empty.
      */
     public EncryptedPrivateKeyInfo(String encrAlgName, byte[] encryptedData)
         throws NoSuchAlgorithmException {
@@ -129,7 +164,19 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Creates an {@code EncryptedPrivateKeyInfo} instance from the
+     * encryption algorithm parameters an its encrypted data.
+     *
+     * @param algParams
+     *            the encryption algorithm parameters.
+     * @param encryptedData
+     *            the encrypted data.
+     * @throws NoSuchAlgorithmException
+     *             if the algorithm name of the specified {@code algParams}
+     *             parameter is not supported.
+     * @throws NullPointerException
+     *             if {@code algParams} or {@code encryptedData} is
+     *             {@code null}.
      */
     public EncryptedPrivateKeyInfo(AlgorithmParameters algParams,
             byte[] encryptedData)
@@ -155,21 +202,28 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the name of the encryption algorithm.
+     *
+     * @return the name of the encryption algorithm.
      */
     public String getAlgName() {
         return algName;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the parameters used by the encryption algorithm.
+     *
+     * @return the parameters used by the encryption algorithm.
      */
     public AlgorithmParameters getAlgParameters() {
         return algParameters;
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the encrypted data of this key.
+     *
+     * @return the encrypted data of this key, each time this method is called a
+     *         new array is returned.
      */
     public byte[] getEncryptedData() {
         byte[] ret = new byte[encryptedData.length];
@@ -178,7 +232,21 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the {@code PKCS8EncodedKeySpec} object extracted from the
+     * encrypted data.
+     * <p>
+     * The cipher must be initialize in either {@code Cipher.DECRYPT_MODE} or
+     * {@code Cipher.UNWRAP_MODE} with the same parameters and key used for
+     * encrypting this.
+     *
+     * @param cipher
+     *            the cipher initialized for decrypting the encrypted data.
+     * @return the extracted {@code PKCS8EncodedKeySpec}.
+     * @throws InvalidKeySpecException
+     *             if the specified cipher is not suited to decrypt the
+     *             encrypted data.
+     * @throws NullPointerException
+     *             if {@code cipher} is {@code null}.
      */
     public PKCS8EncodedKeySpec getKeySpec(Cipher cipher)
         throws InvalidKeySpecException {
@@ -204,7 +272,20 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the {@code PKCS8EncodedKeySpec} object extracted from the
+     * encrypted data.
+     *
+     * @param decryptKey
+     *            the key to decrypt the encrypted data with.
+     * @return the extracted {@code PKCS8EncodedKeySpec}.
+     * @throws NoSuchAlgorithmException
+     *             if no usable cipher can be found to decrypt the encrypted
+     *             data.
+     * @throws InvalidKeyException
+     *             if {@code decryptKey} is not usable to decrypt the encrypted
+     *             data.
+     * @throws NullPointerException
+     *             if {@code decryptKey} is {@code null}.
      */
     public PKCS8EncodedKeySpec getKeySpec(Key decryptKey)
         throws NoSuchAlgorithmException,
@@ -241,7 +322,26 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the {@code PKCS8EncodedKeySpec} object extracted from the
+     * encrypted data.
+     *
+     * @param decryptKey
+     *            the key to decrypt the encrypted data with.
+     * @param providerName
+     *            the name of a provider whose cipher implementation should be
+     *            used.
+     * @return the extracted {@code PKCS8EncodedKeySpec}.
+     * @throws NoSuchProviderException
+     *             if no provider with {@code providerName} can be found.
+     * @throws NoSuchAlgorithmException
+     *             if no usable cipher can be found to decrypt the encrypted
+     *             data.
+     * @throws InvalidKeyException
+     *             if {@code decryptKey} is not usable to decrypt the encrypted
+     *             data.
+     * @throws NullPointerException
+     *             if {@code decryptKey} or {@code providerName} is {@code null}
+     *             .
      */
     public PKCS8EncodedKeySpec getKeySpec(Key decryptKey, String providerName)
         throws NoSuchProviderException, 
@@ -283,7 +383,22 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the {@code PKCS8EncodedKeySpec} object extracted from the
+     * encrypted data.
+     *
+     * @param decryptKey
+     *            the key to decrypt the encrypted data with.
+     * @param provider
+     *            the provider whose cipher implementation should be used.
+     * @return the extracted {@code PKCS8EncodedKeySpec}.
+     * @throws NoSuchAlgorithmException
+     *             if no usable cipher can be found to decrypt the encrypted
+     *             data.
+     * @throws InvalidKeyException
+     *             if {@code decryptKey} is not usable to decrypt the encrypted
+     *             data.
+     * @throws NullPointerException
+     *             if {@code decryptKey} or {@code provider} is {@code null}.
      */
     public PKCS8EncodedKeySpec getKeySpec(Key decryptKey, Provider provider)
         throws NoSuchAlgorithmException,
@@ -323,7 +438,11 @@
     }
 
     /**
-     * @com.intel.drl.spec_ref
+     * Returns the ASN.1 encoded representation of this object.
+     *
+     * @return the ASN.1 encoded representation of this object.
+     * @throws IOException
+     *             if encoding this object fails.
      */
     public byte[] getEncoded() throws IOException {
         if (encoded == null) {



Mime
View raw message