mirror of git://gcc.gnu.org/git/gcc.git
399 lines
16 KiB
Java
399 lines
16 KiB
Java
/* CipherSpi.java -- The cipher service provider interface.
|
|
Copyright (C) 2004 Free Software Foundation, Inc.
|
|
|
|
This file is part of GNU Classpath.
|
|
|
|
GNU Classpath is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2, or (at your option)
|
|
any later version.
|
|
|
|
GNU Classpath is distributed in the hope that it will be useful, but
|
|
WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
|
|
General Public License for more details.
|
|
|
|
You should have received a copy of the GNU General Public License
|
|
along with GNU Classpath; see the file COPYING. If not, write to the
|
|
Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
|
|
02111-1307 USA.
|
|
|
|
Linking this library statically or dynamically with other modules is
|
|
making a combined work based on this library. Thus, the terms and
|
|
conditions of the GNU General Public License cover the whole
|
|
combination.
|
|
|
|
As a special exception, the copyright holders of this library give you
|
|
permission to link this library with independent modules to produce an
|
|
executable, regardless of the license terms of these independent
|
|
modules, and to copy and distribute the resulting executable under
|
|
terms of your choice, provided that you also meet, for each linked
|
|
independent module, the terms and conditions of the license of that
|
|
module. An independent module is a module which is not derived from
|
|
or based on this library. If you modify this library, you may extend
|
|
this exception to your version of the library, but you are not
|
|
obligated to do so. If you do not wish to do so, delete this
|
|
exception statement from your version. */
|
|
|
|
|
|
package javax.crypto;
|
|
|
|
import java.security.AlgorithmParameters;
|
|
import java.security.InvalidAlgorithmParameterException;
|
|
import java.security.InvalidKeyException;
|
|
import java.security.Key;
|
|
import java.security.NoSuchAlgorithmException;
|
|
import java.security.SecureRandom;
|
|
import java.security.spec.AlgorithmParameterSpec;
|
|
|
|
/**
|
|
* <p>This class represents the <i>Service Provider Interface</i>
|
|
* (<b>SPI</b>) for cryptographic ciphers.</p>
|
|
*
|
|
* <p>Providers of cryptographic ciphers must subclass this for every
|
|
* cipher they implement, implementing the abstract methods as
|
|
* appropriate, then provide an entry that points to the subclass in
|
|
* their implementation of {@link java.security.Provider}.</p>
|
|
*
|
|
* <p>CipherSpi objects are instantiated along with {@link Cipher}s when
|
|
* the {@link Cipher#getInstance(java.lang.String)} methods are invoked.
|
|
* Particular ciphers are referenced by a <i>transformation</i>, which
|
|
* is a String consisting of the cipher's name or the ciper's name
|
|
* followed by a mode and a padding. Transformations all follow the
|
|
* general form:</p>
|
|
*
|
|
* <ul>
|
|
* <li><i>algorithm</i>, or</li>
|
|
* <li><i>algorithm</i>/<i>mode</i>/<i>padding</i>
|
|
* </ul>
|
|
*
|
|
* <p>Cipher names in the master {@link java.security.Provider} class
|
|
* may be:</p>
|
|
*
|
|
* <ol>
|
|
* <li>The algorithm's name, which uses a pluggable mode and padding:
|
|
* <code>Cipher.<i>algorithm</i></code></li>
|
|
* <li>The algorithm's name and the mode, which uses pluggable padding:
|
|
* <code>Cipher.<i>algorithm</i>/<i>mode</i></code></li>
|
|
* <li>The algorithm's name and the padding, which uses a pluggable
|
|
* mode: <code>Cipher.<i>algorithm</i>//<i>padding</i></code></li>
|
|
* <li>The algorihtm's name, the mode, and the padding:
|
|
* <code>Cipher.<i>algorithm</i>/<i>mode</i>/<i>padding</i></code></li>
|
|
* </ol>
|
|
*
|
|
* <p>When any {@link Cipher#getInstance(java.lang.String)} method is
|
|
* invoked, the following happens if the transformation is simply
|
|
* <i>algorithm</i>:</p>
|
|
*
|
|
* <ol>
|
|
* <li>If the provider defines a <code>CipherSpi</code> implementation
|
|
* for "<i>algorithm</i>", return it. Otherwise throw a {@link
|
|
* java.security.NoSuchAlgorithmException}.</li>
|
|
* </ol>
|
|
*
|
|
* <p>If the transformation is of the form
|
|
* <i>algorithm</i>/<i>mode</i>/<i>padding</i>:</p>
|
|
*
|
|
* <ol>
|
|
* <li>If the provider defines a <code>CipherSpi</code> subclass for
|
|
* "<i>algorithm</i>/<i>mode</i>/<i>padding</i>", return it. Otherwise
|
|
* go to step 2.</li>
|
|
*
|
|
* <li>If the provider defines a <code>CipherSpi</code> subclass for
|
|
* "<i>algorithm</i>/<i>mode</i>", instatiate it, call {@link
|
|
* #engineSetPadding(java.lang.String)} for the padding name, and return
|
|
* it. Otherwise go to step 3.</li>
|
|
*
|
|
* <li>If the provider defines a <code>CipherSpi</code> subclass for
|
|
* "<i>algorithm</i>//<i>padding</i>", instatiate it, call {@link
|
|
* #engineSetMode(java.lang.String)} for the mode name, and return
|
|
* it. Otherwise go to step 4.</li>
|
|
*
|
|
* <li>If the provider defines a <code>CipherSpi</code> subclass for
|
|
* "<i>algorithm</i>", instatiate it, call {@link
|
|
* #engineSetMode(java.lang.String)} for the mode name, call {@link
|
|
* #engineSetPadding(java.lang.String)} for the padding name, and return
|
|
* it. Otherwise throw a {@link java.security.NoSuchAlgorithmException}.</li>
|
|
* </ol>
|
|
*
|
|
* @author Casey Marshall (csm@gnu.org)
|
|
* @since 1.4
|
|
*/
|
|
public abstract class CipherSpi
|
|
{
|
|
|
|
// Constructors.
|
|
// ------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Create a new CipherSpi.
|
|
*/
|
|
public CipherSpi()
|
|
{
|
|
}
|
|
|
|
// Abstract methods to be implemented by providers.
|
|
// ------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Finishes a multi-part transformation or transforms a portion of a
|
|
* byte array, and returns the transformed bytes.
|
|
*
|
|
* @param input The input bytes.
|
|
* @param inputOffset The index in the input at which to start.
|
|
* @param inputLength The number of bytes to transform.
|
|
* @return The transformed bytes in a new array.
|
|
* @throws javax.crypto.IllegalBlockSizeException If this instance has
|
|
* no padding and the input size is not a multiple of the
|
|
* block size.
|
|
* @throws javax.crypto.BadPaddingException If this instance is being
|
|
* used for decryption and the padding is not appropriate for
|
|
* this instance's padding scheme.
|
|
*/
|
|
protected abstract byte[]
|
|
engineDoFinal(byte[] input, int inputOffset, int inputLength)
|
|
throws IllegalBlockSizeException, BadPaddingException;
|
|
|
|
/**
|
|
* Finishes a multi-part transformation or transforms a portion of a
|
|
* byte array, and stores the transformed bytes in the supplied array.
|
|
*
|
|
* @param input The input bytes.
|
|
* @param inputOffset The index in the input at which to start.
|
|
* @param inputLength The number of bytes to transform.
|
|
* @param output The output byte array.
|
|
* @param outputOffset The index in the output array at which to start.
|
|
* @return The number of transformed bytes stored in the output array.
|
|
* @throws javax.crypto.IllegalBlockSizeException If this instance has
|
|
* no padding and the input size is not a multiple of the
|
|
* block size.
|
|
* @throws javax.crypto.BadPaddingException If this instance is being
|
|
* used for decryption and the padding is not appropriate for
|
|
* this instance's padding scheme.
|
|
* @throws javax.crypto.ShortBufferException If there is not enough
|
|
* space in the output array for the transformed bytes.
|
|
*/
|
|
protected abstract int
|
|
engineDoFinal(byte[] input, int inputOffset, int inputLength,
|
|
byte[] output, int outputOffset)
|
|
throws IllegalBlockSizeException, BadPaddingException, ShortBufferException;
|
|
|
|
/**
|
|
* Returns the block size of the underlying cipher.
|
|
*
|
|
* @return The block size.
|
|
*/
|
|
protected abstract int engineGetBlockSize();
|
|
|
|
/**
|
|
* Returns the initializaiton vector this cipher was initialized with,
|
|
* if any.
|
|
*
|
|
* @return The IV, or null if this cipher uses no IV or if this
|
|
* instance has not been initialized yet.
|
|
*/
|
|
protected abstract byte[] engineGetIV();
|
|
|
|
/**
|
|
* <p>Return the length of the given key in bits.</p>
|
|
*
|
|
* <p>For compatibility this method is not declared
|
|
* <code>abstract</code>, and the default implementation will throw an
|
|
* {@link java.lang.UnsupportedOperationException}. Concrete
|
|
* subclasses should override this method to return the correct
|
|
* value.</p>
|
|
*
|
|
* @param key The key to get the size for.
|
|
* @return The size of the key, in bits.
|
|
* @throws java.security.InvalidKeyException If the key's length
|
|
* cannot be determined by this implementation.
|
|
*/
|
|
protected int engineGetKeySize(Key key) throws InvalidKeyException
|
|
{
|
|
throw new UnsupportedOperationException();
|
|
}
|
|
|
|
/**
|
|
* <p>Returns the size, in bytes, an output buffer must be for a call
|
|
* to {@link #engineUpdate(byte[],int,int,byte[],int)} or {@link
|
|
* #engineDoFinal(byte[],int,int,byte[],int)} to succeed.</p>
|
|
*
|
|
* <p>The actual output length may be smaller than the value returned
|
|
* by this method, as it considers the padding length as well. The
|
|
* length considered is the argument plus the length of any buffered,
|
|
* unprocessed bytes.</p>
|
|
*
|
|
* @param inputLength The input length, in bytes.
|
|
* @return The size an output buffer must be.
|
|
*/
|
|
protected abstract int engineGetOutputSize(int inputLength);
|
|
|
|
/**
|
|
* Returns the parameters that this cipher is using. This may be the
|
|
* parameters used to initialize this cipher, or it may be parameters
|
|
* that have been initialized with random values.
|
|
*
|
|
* @return This cipher's parameters, or <code>null</code> if this
|
|
* cipher does not use parameters.
|
|
*/
|
|
protected abstract AlgorithmParameters engineGetParameters();
|
|
|
|
/**
|
|
* Initializes this cipher with an operation mode, key, and source of
|
|
* randomness. If this cipher requires any other initializing data,
|
|
* for example an initialization vector, then it should generate it
|
|
* from the provided source of randomness.
|
|
*
|
|
* @param opmode The operation mode, one of {@link
|
|
* Cipher#DECRYPT_MODE}, {@link Cipher#ENCRYPT_MODE}, {@link
|
|
* Cipher#UNWRAP_MODE}, or {@link Cipher#WRAP_MODE}.
|
|
* @param key The key to initialize this cipher with.
|
|
* @param random The source of random bytes to use.
|
|
* @throws java.security.InvalidKeyException If the given key is not
|
|
* acceptable for this implementation.
|
|
*/
|
|
protected abstract void engineInit(int opmode, Key key, SecureRandom random)
|
|
throws InvalidKeyException;
|
|
|
|
/**
|
|
* Initializes this cipher with an operation mode, key, parameters,
|
|
* and source of randomness. If this cipher requires any other
|
|
* initializing data, for example an initialization vector, then it should
|
|
* generate it from the provided source of randomness.
|
|
*
|
|
* @param opmode The operation mode, one of {@link
|
|
* Cipher#DECRYPT_MODE}, {@link Cipher#ENCRYPT_MODE}, {@link
|
|
* Cipher#UNWRAP_MODE}, or {@link Cipher#WRAP_MODE}.
|
|
* @param key The key to initialize this cipher with.
|
|
* @param params The algorithm parameters to initialize with.
|
|
* @param random The source of random bytes to use.
|
|
* @throws java.security.InvalidAlgorithmParameterException If the
|
|
* given parameters are not appropriate for this
|
|
* implementation.
|
|
* @throws java.security.InvalidKeyException If the given key is not
|
|
* acceptable for this implementation.
|
|
*/
|
|
protected abstract void
|
|
engineInit(int opmode, Key key, AlgorithmParameters params,
|
|
SecureRandom random)
|
|
throws InvalidAlgorithmParameterException, InvalidKeyException;
|
|
|
|
/**
|
|
* Initializes this cipher with an operation mode, key, parameters,
|
|
* and source of randomness. If this cipher requires any other
|
|
* initializing data, for example an initialization vector, then it should
|
|
* generate it from the provided source of randomness.
|
|
*
|
|
* @param opmode The operation mode, one of {@link
|
|
* Cipher#DECRYPT_MODE}, {@link Cipher#ENCRYPT_MODE}, {@link
|
|
* Cipher#UNWRAP_MODE}, or {@link Cipher#WRAP_MODE}.
|
|
* @param key The key to initialize this cipher with.
|
|
* @param params The algorithm parameters to initialize with.
|
|
* @param random The source of random bytes to use.
|
|
* @throws java.security.InvalidAlgorithmParameterException If the
|
|
* given parameters are not appropriate for this
|
|
* implementation.
|
|
* @throws java.security.InvalidKeyException If the given key is not
|
|
* acceptable for this implementation.
|
|
*/
|
|
protected abstract void
|
|
engineInit(int opmode, Key key, AlgorithmParameterSpec params,
|
|
SecureRandom random)
|
|
throws InvalidAlgorithmParameterException, InvalidKeyException;
|
|
|
|
/**
|
|
* Set the mode in which this cipher is to run.
|
|
*
|
|
* @param mode The name of the mode to use.
|
|
* @throws java.security.NoSuchAlgorithmException If the mode is
|
|
* not supported by this cipher's provider.
|
|
*/
|
|
protected abstract void engineSetMode(String mode)
|
|
throws NoSuchAlgorithmException;
|
|
|
|
/**
|
|
* Set the method with which the input is to be padded.
|
|
*
|
|
* @param padding The name of the padding to use.
|
|
* @throws javax.crypto.NoSuchPaddingException If the padding is not
|
|
* supported by this cipher's provider.
|
|
*/
|
|
protected abstract void engineSetPadding(String padding)
|
|
throws NoSuchPaddingException;
|
|
|
|
/**
|
|
* <p>Unwraps a previously-wrapped key.</p>
|
|
*
|
|
* <p>For compatibility this method is not declared
|
|
* <code>abstract</code>, and the default implementation will throw an
|
|
* {@link java.lang.UnsupportedOperationException}.</p>
|
|
*
|
|
* @param wrappedKey The wrapped key.
|
|
* @param wrappedKeyAlgorithm The name of the algorithm used to wrap
|
|
* this key.
|
|
* @param wrappedKeyType The type of wrapped key; one of
|
|
* {@link Cipher#PRIVATE_KEY},
|
|
* {@link Cipher#PUBLIC_KEY}, or
|
|
* {@link Cipher#SECRET_KEY}.
|
|
* @return The unwrapped key.
|
|
* @throws java.security.InvalidKeyException If the key cannot be
|
|
* unwrapped, or if <code>wrappedKeyType</code> is an
|
|
* inappropriate type for the unwrapped key.
|
|
* @throws java.security.NoSuchAlgorithmException If the
|
|
* <code>wrappedKeyAlgorithm</code> is unknown.
|
|
*/
|
|
protected Key engineUnwrap(byte[] wrappedKey, String wrappedKeyAlgorithm,
|
|
int wrappedKeyType)
|
|
throws InvalidKeyException, NoSuchAlgorithmException
|
|
{
|
|
throw new UnsupportedOperationException();
|
|
}
|
|
|
|
/**
|
|
* Continue with a multi-part transformation, returning a new array of
|
|
* the transformed bytes.
|
|
*
|
|
* @param input The next input bytes.
|
|
* @param inputOffset The index in the input array from which to start.
|
|
* @param inputLength The number of bytes to input.
|
|
* @return The transformed bytes.
|
|
*/
|
|
protected abstract byte[]
|
|
engineUpdate(byte[] input, int inputOffset, int inputLength);
|
|
|
|
/**
|
|
* Continue with a multi-part transformation, storing the transformed
|
|
* bytes into the specified array.
|
|
*
|
|
* @param input The next input bytes.
|
|
* @param inputOffset The index in the input from which to start.
|
|
* @param inputLength The number of bytes to input.
|
|
* @param output The output buffer.
|
|
* @param outputOffset The index in the output array from which to start.
|
|
* @return The transformed bytes.
|
|
* @throws javax.crypto.ShortBufferException If there is not enough
|
|
* space in the output array to store the transformed bytes.
|
|
*/
|
|
protected abstract int
|
|
engineUpdate(byte[] input, int inputOffset, int inputLength,
|
|
byte[] output, int outputOffset)
|
|
throws ShortBufferException;
|
|
|
|
/**
|
|
* <p>Wrap a key.</p>
|
|
*
|
|
* <p>For compatibility this method is not declared
|
|
* <code>abstract</code>, and the default implementation will throw an
|
|
* {@link java.lang.UnsupportedOperationException}.</p>
|
|
*
|
|
* @param key The key to wrap.
|
|
* @return The wrapped key.
|
|
* @throws java.security.InvalidKeyException If the key cannot be
|
|
* wrapped.
|
|
*/
|
|
protected byte[] engineWrap(Key key) throws InvalidKeyException, IllegalBlockSizeException
|
|
{
|
|
throw new UnsupportedOperationException();
|
|
}
|
|
}
|