You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@harmony.apache.org by te...@apache.org on 2009/04/23 14:57:19 UTC
svn commit: r767909 [1/3] - in
/harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto:
./ interfaces/ spec/
Author: tellison
Date: Thu Apr 23 12:57:17 2009
New Revision: 767909
URL: http://svn.apache.org/viewvc?rev=767909&view=rev
Log:
Apply patch for HARMONY-6168 (Javadocs for javax.crypto.*)
Modified:
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/Cipher.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherSpi.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/ExemptionMechanism.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismException.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/ExemptionMechanismSpi.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/IllegalBlockSizeException.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/KeyAgreement.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/KeyAgreementSpi.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/KeyGenerator.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/KeyGeneratorSpi.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/Mac.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/MacSpi.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/NoSuchPaddingException.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/NullCipher.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/SealedObject.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/SecretKey.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/SecretKeyFactory.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/SecretKeyFactorySpi.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/ShortBufferException.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/interfaces/DHKey.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/interfaces/DHPrivateKey.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/interfaces/DHPublicKey.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/interfaces/PBEKey.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/DESKeySpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/DESedeKeySpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/DHGenParameterSpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/DHParameterSpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/DHPrivateKeySpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/DHPublicKeySpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/IvParameterSpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/OAEPParameterSpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/PBEKeySpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/PBEParameterSpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/PSource.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/RC2ParameterSpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/RC5ParameterSpec.java
harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/spec/SecretKeySpec.java
Modified: harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java?rev=767909&r1=767908&r2=767909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java (original)
+++ harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/BadPaddingException.java Thu Apr 23 12:57:17 2009
@@ -25,8 +25,8 @@
import java.security.GeneralSecurityException;
/**
- * @com.intel.drl.spec_ref
- *
+ * The exception that is thrown when a padding mechanism is expected for the
+ * input data, but the input data does not have the proper padding bytes.
*/
public class BadPaddingException extends GeneralSecurityException {
@@ -36,16 +36,17 @@
private static final long serialVersionUID = -5315033893984728443L;
/**
- * @com.intel.drl.spec_ref
+ * Creates a new instance of {@code BadPaddingException} with a message.
*
+ * @param msg
+ * the message
*/
public BadPaddingException(String msg) {
super(msg);
}
/**
- * @com.intel.drl.spec_ref
- *
+ * Creates a new instance of {@code BadPaddingException} with no message.
*/
public BadPaddingException() {
}
Modified: harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/Cipher.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/Cipher.java?rev=767909&r1=767908&r2=767909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/Cipher.java (original)
+++ harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/Cipher.java Thu Apr 23 12:57:17 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/trunk/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java?rev=767909&r1=767908&r2=767909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherInputStream.java Thu Apr 23 12:57:17 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/trunk/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java?rev=767909&r1=767908&r2=767909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java (original)
+++ harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherOutputStream.java Thu Apr 23 12:57:17 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/trunk/modules/crypto/src/main/java/javax/crypto/CipherSpi.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherSpi.java?rev=767909&r1=767908&r2=767909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherSpi.java (original)
+++ harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/CipherSpi.java Thu Apr 23 12:57:17 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/trunk/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java?rev=767909&r1=767908&r2=767909&view=diff
==============================================================================
--- harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java (original)
+++ harmony/enhanced/classlib/trunk/modules/crypto/src/main/java/javax/crypto/EncryptedPrivateKeyInfo.java Thu Apr 23 12:57:17 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) {