Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Cryptix V3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## java.security
Class Cipher

    java.lang.Object
      |
      +--java.security.IJCE_Traceable
            |
            +--java.security.Cipher

Direct Known Subclasses:
  Blowfish, CAST5, DES, DES_EDE3, DES2X, DESX, IDEA, LOKI91, Mode, RawElGamalCipher, RawRSACipher, RC2, RC4, Rijndael, SAFER, SPEED, Square

public abstract class Cipher
extends java.security.IJCE_Traceable
implements Parameterized

This class is used to provide the functionality of a general purpose encryption algorithm, such as DES or RSA. Encryption is used to ensure confidentiality of digital data.

This class follows the general algorithm architecture found elsewhere in the security API: the base class provides an algorithm-independent interface to basic encryption functionality, with provider implementation subclassing a subset of the behaviours.

Like other algorithm-based classes in Java Security, the Cipher class is separated between application and provider interfaces:

Cipher API (Application Programming Interface)
  This is the interface of methods called by applications needing encryption services. The API consists of all public methods.
Cipher SPI (Service Provider Interface)
  This is the interface implemented by providers that supply specific algorithms. It consists of all methods whose names are prefixed by `engine`. Each such method is usually called by a correspondingly-named public API method. For example, the `engineInitEncrypt` method is called by the `initEncrypt` method.

Ciphers represented by this class satisfy the following constraints:

- At any point in time the cipher has a plaintext block size, and a ciphertext block size, both expressed in bytes. These sizes may change when initEncrypt or initDecrypt are called, and they may be invalid before the cipher is initialized, but they do not change at other times.
- A plaintext block encrypts to exactly one ciphertext block, and a ciphertext block decrypts to exactly one plaintext block.

Byte-oriented stream ciphers (or ciphers in CFB and OFB modes, for example) have plaintext and ciphertext block sizes of 1 byte. For public key ciphers, it is common for the block sizes to be dependent on the length of some parameter of the public key.

A block cipher implementation may either implement its own buffering (by passing `implBuffering == true` to the constructor), or leave it to the Cipher superclass (`implBuffering` == false). When the implementation handles buffering, data passed to `update` is passed directly on to `engineUpdate`, and data passed to `crypt` is passed to `engineUpdate`, followed immediately by a call to `engineCrypt`.

When the Cipher superclass handles buffering, up to one block is buffered, in order to ensure that the length of data passed to `engineUpdate` is always a multiple of the block size. In this case the `engineCrypt` method is not used.

Cipher implementations are not required or expected to be threadsafe. If methods of a single Cipher object are called simultaneously by more than one thread, the result will be unpredictable.

Copyright © 1997 Systemics Ltd on behalf of the Cryptix Development Team.
All rights reserved.

$Revision: 1.8 $

Since:
  IJCE 1.0.0
Author:
  David Hopwood, Raif S. Naffah

Field Summary
`static int` | `DECRYPT` The state of the cipher when it is ready to decrypt, that is, the state it is in right after a call to `initDecrypt`.
`static int` | `ENCRYPT` The state of the cipher when it is ready to encrypt, that is, the state it is in right after a call to `initEncrypt`.
`static int` | `UNINITIALIZED` The state of the cipher object when it is uninitialized, that is, the state it is in right after it has been created.

Constructor Summary
`protected` | `Cipher()` Deprecated.
`protected` | `Cipher(boolean implBuffering, boolean implPadding, String provider)` Constructor for a Cipher.
`protected` | `Cipher(boolean implBuffering, String provider, String algorithm)` This constructor is identical to the previous one (with arguments boolean, boolean, String), except that it does not have the redundant implPadding parameter, and also allows the algorithm name to be specified.

Method Summary
`int` | `blockSize()` Returns the length of a block for this cipher.
`Object` | `clone()` Returns a clone of this cipher.
`byte[]` | `crypt(byte[] in)` Encrypts or decrypts the specified array of data, which will be automatically padded/unpadded as necessary.
`byte[]` | `crypt(byte[] in, int offset, int length)` Encrypts or decrypts the specified array of data, which will be automatically padded/unpadded as necessary.
`int` | `crypt(byte[] in, int inOffset, int inLen, byte[] out, int outOffset)` Encrypts or decrypts the specified subarray of data, pads or unpads it as necessary, and places the result in the specified output buffer.
`byte[]` | `doFinal(byte[] in)` Equivalent to `crypt(in)`.
`byte[]` | `doFinal(byte[] in, int offset, int length)` Equivalent to `crypt(in, offset, length)`.
`int` | `doFinal(byte[] in, int inOffset, int inLen, byte[] out)` Equivalent to `crypt(in, inOffset, inLen, out, 0)`.
`int` | `doFinal(byte[] in, int inOffset, int inLen, byte[] out, int outOffset)` Equivalent to `crypt(in, inOffset, inLen, out, outOffset)`.
`protected int` | `engineBlockSize()` SPI: Returns the length of a block, in bytes.
`protected int` | `engineCiphertextBlockSize()` SPI: Returns the length of a ciphertext block, in bytes.
`protected int` | `engineCrypt(byte[] out, int outOffset)` SPI: Process data buffered by this cipher implementation.
`protected Object` | `engineGetParameter(String param)` SPI: Gets the value of the specified algorithm parameter.
`protected int` | `engineInBufferSize(int outLen, boolean isFinal)` SPI: Returns the minimum number of bytes of input, that will cause an output of outLen bytes from a call to `engineUpdate` (when isFinal is false), or successive calls to both `engineUpdate` and `engineCrypt` (when isFinal is true).
`protected abstract void` | `engineInitDecrypt(Key key)` SPI: Initializes this cipher for decryption, using the specified key.
`protected abstract void` | `engineInitEncrypt(Key key)` SPI: Initializes this cipher for encryption, using the specified key.
`protected int` | `engineOutBufferSize(int inLen, boolean isFinal)` SPI: Returns the length of output buffer required for a given length of input, in bytes.
`protected int` | `enginePlaintextBlockSize()` SPI: Returns the length of a plaintext block, in bytes.
`protected void` | `engineSetPaddingScheme(PaddingScheme padding)` SPI: Sets the object that will implement padding for this cipher.
`protected void` | `engineSetParameter(String param, Object value)` SPI: Sets the specified algorithm parameter to the specified value.
`protected abstract int` | `engineUpdate(byte[] in, int inOffset, int inLen, byte[] out, int outOffset)` SPI: This is the main engine method for updating data.
`String` | `getAlgorithm()` Returns this algorithm's standard cipher name (not including mode and padding).
`static String[]` | `getAlgorithms()` Gets the standard names of all Ciphers implemented by any installed provider.
`static String[]` | `getAlgorithms(Provider provider)` Gets the standard names of all Ciphers implemented by a provider.
`int` | `getCiphertextBlockSize()` Returns the length of a ciphertext block, in bytes.
`int` | `getInputBlockSize()` Returns the length of an input block, in bytes.
`static Cipher` | `getInstance(Cipher cipher, Mode mode, PaddingScheme padding)` Generates a new Cipher object by composing the given Cipher, Mode and PaddingScheme objects.
`static Cipher` | `getInstance(String algorithm)` Generates a Cipher object that implements the given algorithm.
`static Cipher` | `getInstance(String algorithm, String provider)` Generates a Cipher object that implements the given cipher, from the given provider.
`String` | `getMode()` Returns this algorithm's standard mode name.
`int` | `getOutputBlockSize()` Returns the length of an output block, in bytes.
`String` | `getPadding()` Returns this algorithm's standard padding scheme name.
`protected PaddingScheme` | `getPaddingScheme()` Returns the object implementing padding for this cipher, or null if there is no such object.
`Object` | `getParameter(String param)` Gets the value of the specified algorithm parameter.
`int` | `getPlaintextBlockSize()` Returns the length of a plaintext block, in bytes.
`String` | `getProvider()` Returns the name of the provider of this cipher.
`int` | `getState()` Returns the state of this Cipher object.
`int` | `inBufferSize(int outLen)` Returns the minimum number of bytes of input, that will cause an output of outLen bytes from a call to `update` (i.e.
`int` | `inBufferSizeFinal(int outLen)` Returns the minimum number of bytes of input, that will cause an output of outLen bytes from a call to `crypt` (including padding for the final block of the stream, if applicable).
`void` | `initDecrypt(Key key)` Initializes this cipher for decryption, using the specified key.
`void` | `initEncrypt(Key key)` Initializes this cipher for encryption, using the specified key.
`boolean` | `isPaddingBlockCipher()` Returns true if this cipher is a padding block cipher.
`int` | `outBufferSize(int inLen)` Returns the size of the buffer necessary to hold the output resulting from a call to `update` (i.e.
`int` | `outBufferSizeFinal(int inLen)` Returns the size of the buffer necessary to hold the output resulting from a call to `crypt` (including padding for the final block of the stream, if applicable).
`void` | `setParameter(String param, Object value)` Sets the specified algorithm parameter to the specified value.
`String` | `toString()`
`byte[]` | `update(byte[] in)` Encrypts or decrypts the specified array of data, which is not the final data in this stream.
`byte[]` | `update(byte[] in, int offset, int length)` Encrypts or decrypts the specified subarray of data, which is not the final data in this stream.
`int` | `update(byte[] in, int inOffset, int inLen, byte[] out)` Encrypts or decrypts the specified subarray of data, which is not the final data in this stream, and places the result in the specified output buffer (starting at offset 0).
`int` | `update(byte[] in, int inOffset, int inLen, byte[] out, int outOffset)` Encrypts or decrypts the specified subarray of data, which is not the final data in this stream, and places the result in the specified output buffer.

Methods inherited from class java.lang.Object
`equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

Field Detail

### UNINITIALIZED

    public static final int UNINITIALIZED

  The state of the cipher object when it is uninitialized, that is, the state it is in right after it has been created.

### ENCRYPT

    public static final int ENCRYPT

  The state of the cipher when it is ready to encrypt, that is, the state it is in right after a call to `initEncrypt`.
  See Also:
    `initEncrypt(java.security.Key)`

### DECRYPT

    public static final int DECRYPT

  The state of the cipher when it is ready to decrypt, that is, the state it is in right after a call to `initDecrypt`.
  See Also:
    `initDecrypt(java.security.Key)`

Constructor Detail

### Cipher

    protected Cipher()

  Deprecated.

  The JCE docs say: "Constructor used for dynamic instantiation." I don't understand why this is needed. --DJH

### Cipher

    protected Cipher(boolean implBuffering,
                     boolean implPadding,
                     String provider)

  Constructor for a Cipher. This constructor is only for use by subclasses, which should pass the correct arguments to convey their behaviour to the superclass. Applications cannot call this constructor directly.

  For byte-oriented stream ciphers (where the input block size is 1), buffering is not needed, and the implBuffering parameter has no effect.

  In this version of IJCE, implPadding must be false. If it is true, an `IllegalArgumentException` is thrown.

  Parameters:
    `implBuffering` - if true, this argument indicates that data will always be passed from update/crypt to engineUpdate/engineCrypt without modification.
    `implPadding` - must be false.
    `provider` - the name of the provider of the underlying cryptographic engine.

### Cipher

    protected Cipher(boolean implBuffering,
                     String provider,
                     String algorithm)

  This constructor is identical to the previous one (with arguments boolean, boolean, String), except that it does not have the redundant implPadding parameter, and also allows the algorithm name to be specified.

  This constructor is not supported in JavaSoft's version of JCE.

  Parameters:
    `implBuffering` - if true, this argument indicates that data will always be passed from update/crypt to engineUpdate/engineCrypt without modification.
    `provider` - the name of the provider of the underlying cryptographic engine.
    `algorithm` - the name of this algorithm (optionally with mode and padding, separated by '/'), as it is configured in the properties file.

Method Detail

### getPaddingScheme

    protected final PaddingScheme getPaddingScheme()

  Returns the object implementing padding for this cipher, or null if there is no such object.

### getInstance

    public static Cipher getInstance(String algorithm)
                              throws NoSuchAlgorithmException

  Generates a Cipher object that implements the given algorithm. If the default provider package contains a class implementing the algorithm, an instance of that class is returned. If it is not available in the default package, other packages are searched.

  Any of the following formats can be used for the algorithm name:

  cipher "/" mode "/" padding
    all algorithm components - cipher, mode, and padding - are specified (these may be aliases).
  cipher "/" mode
    the padding is assumed to be "NONE".
  cipher
    the mode is assumed to be "ECB", and the padding to be "NONE".

  See International JCE Standard Algorithm Names for a list of Cipher algorithm names.

  Parameters:
    `algorithm` - the algorithm name, as described above.
  Returns:
    the new Cipher object, in the UNINITIALIZED state.
  Throws:
    NoSuchAlgorithmException - if the algorithm is not available from any provider.

### getInstance

    public static Cipher getInstance(String algorithm,
                                     String provider)
                              throws NoSuchAlgorithmException,
                                     NoSuchProviderException

  Generates a Cipher object that implements the given cipher, from the given provider. The format of the cipher specification is as described for `getInstance(String algorithm)`.

  If the algorithm is implemented using more than one component (cipher, mode, and padding scheme), all of them must come from the given provider. More flexibility can be obtained by using the `getInstance(Cipher, Mode, PaddingScheme)` factory method. For example, to request "DES" from the SUN provider, "CBC" from the Cryptix provider, and "PKCS#5" from any provider, use:

          Cipher.getInstance(
              Cipher.getInstance("DES", "SUN"),
              Mode.getInstance("CBC", "Cryptix"),
              PaddingScheme.getInstance("PKCS#5")
          )

  See International JCE Standard Algorithm Names for a list of Cipher algorithm names.

  Parameters:
    `algorithm` - the cipher specification.
  Returns:
    the new Cipher object, in the UNINITIALIZED state.
  Throws:
    NoSuchAlgorithmException - if the algorithm is not available from the provider.
    NoSuchProviderException - if the provider is not available in the environment.

### getInstance

    public static Cipher getInstance(Cipher cipher,
                                     Mode mode,
                                     PaddingScheme padding)

  Generates a new Cipher object by composing the given Cipher, Mode and PaddingScheme objects. mode may be null (indicating ECB), and padding may be null (indicating NONE).

  This method is not supported in JavaSoft's version of JCE.

  Throws:
    NullPointerException - if cipher == null

### getState

    public final int getState()

  Returns the state of this Cipher object. Possible states are:

  UNINITIALIZED
    The cipher has not been initialized.
  ENCRYPT
    The cipher has been initialized for encryption. It may be used for encryption only.
  DECRYPT
    The cipher has been initialized for decryption. It may be used for decryption only.
  Returns:
    the state of this cipher object.
  See Also:
    `UNINITIALIZED`, `ENCRYPT`, `DECRYPT`

### getAlgorithm

    public final String getAlgorithm()

  Returns this algorithm's standard cipher name (not including mode and padding).

  See International JCE Standard Algorithm Names for a list of Cipher algorithm names.

  Returns:
    the standard cipher name (such as "DES").

### getMode

    public final String getMode()

  Returns this algorithm's standard mode name.

  See International JCE Standard Algorithm Names for a list of Mode algorithm names.

  Returns:
    the algorithm's standard mode name (such as "CBC")

### getPadding

    public final String getPadding()

  Returns this algorithm's standard padding scheme name.

  See International JCE Standard Algorithm Names for a list of PaddingScheme algorithm names.

  Returns:
    the algorithm's standard padding scheme name (such as "PKCS#7" or "NONE")

### getProvider

    public final String getProvider()

  Returns the name of the provider of this cipher.
  Returns:
    the provider name (such as "SUN" or "Cryptix")

### isPaddingBlockCipher

    public final boolean isPaddingBlockCipher()

  Returns true if this cipher is a padding block cipher.

  A cipher is a padding block cipher iff `getPlaintextBlockSize() > 1 && getPaddingScheme() != null`. If getPlaintextBlockSize throws an exception, so will this method.

  This method is needed because `CipherInputStream` and `CipherOutputStream` use a different buffering algorithm for padding block ciphers.

  This method is not supported in JavaSoft's version of JCE.

### outBufferSize

    public final int outBufferSize(int inLen)

  Returns the size of the buffer necessary to hold the output resulting from a call to `update` (i.e. not including padding). This call takes into account any incomplete block currently being buffered.
  Parameters:
    `inLen` - the number of bytes to process.
  Throws:
    IllegalArgumentException - if inLen < 0

### outBufferSizeFinal

    public final int outBufferSizeFinal(int inLen)

  Returns the size of the buffer necessary to hold the output resulting from a call to `crypt` (including padding for the final block of the stream, if applicable). This call takes into account any incomplete block currently being buffered.

  This method is not supported in JavaSoft's version of JCE.

  Parameters:
    `inLen` - the number of bytes to process.
  Throws:
    IllegalArgumentException - if inLen < 0

### inBufferSize

    public final int inBufferSize(int outLen)

  Returns the minimum number of bytes of input, that will cause an output of outLen bytes from a call to `update` (i.e. not including padding). This call takes into account any incomplete block currently being buffered.

  This is used by `CipherInputStream`, for example, to calculate how much data must be read from its underlying stream before encryption or decryption.

  This method is not supported in JavaSoft's version of JCE.

  Parameters:
    `outLen` - the number of bytes of output required.
  Throws:
    IllegalArgumentException - if outLen < 0

### inBufferSizeFinal

    public final int inBufferSizeFinal(int outLen)

  Returns the minimum number of bytes of input, that will cause an output of outLen bytes from a call to `crypt` (including padding for the final block of the stream, if applicable). This call takes into account any incomplete block currently being buffered.

  This method is not supported in JavaSoft's version of JCE.

  Parameters:
    `outLen` - the number of bytes of output required.
  Throws:
    IllegalArgumentException - if outLen < 0

### blockSize

    public final int blockSize()

  Returns the length of a block for this cipher. If plaintext and ciphertext blocks are different lengths, this method throws an IllegalBlockSizeException.
  Returns:
    the length in bytes of a block.
  Throws:
    IllegalBlockSizeException - if getPlaintextBlockSize() != getCiphertextBlockSize()

### getInputBlockSize

    public final int getInputBlockSize()

  Returns the length of an input block, in bytes. When the cipher is in encryption mode, this is the length of a plaintext block. When in decryption mode, it is the length of a ciphertext block.

  This method is not supported in JavaSoft's version of JCE.

  Returns:
    the length in bytes of an input block for this cipher.
  Throws:
    Error - if the cipher is uninitialized.

### getOutputBlockSize

    public final int getOutputBlockSize()

  Returns the length of an output block, in bytes. When the cipher is in encryption mode, this is the length of a ciphertext block. When in decryption mode, it is the length of a plaintext block.

  This method is not supported in JavaSoft's version of JCE.

  Returns:
    the length in bytes of an output block for this cipher.
  Throws:
    Error - if the cipher is uninitialized.

### getPlaintextBlockSize

    public final int getPlaintextBlockSize()

  Returns the length of a plaintext block, in bytes. For byte-oriented stream ciphers, this method returns 1.

  This method is not supported in JavaSoft's version of JCE.

  Returns:
    the length in bytes of a plaintext block for this cipher.

### getCiphertextBlockSize

    public final int getCiphertextBlockSize()

  Returns the length of a ciphertext block, in bytes. For byte-oriented stream ciphers, this method returns 1.

  This method is not supported in JavaSoft's version of JCE.

  Returns:
    the length in bytes of a ciphertext block for this cipher.

### initEncrypt

    public final void initEncrypt(Key key)
                           throws KeyException

  Initializes this cipher for encryption, using the specified key. A successful call to this method puts the cipher in the ENCRYPT state. This method may be called on a cipher in any state. Any state information (key, feedback buffer, ...) is lost and reset.
  Parameters:
    `key` - the key to use for encryption.
  Throws:
    NullPointerException - if key == null
    KeyException - if the key is invalid.

### initDecrypt

    public final void initDecrypt(Key key)
                           throws KeyException

  Initializes this cipher for decryption, using the specified key. A successful call to this method puts the cipher in the DECRYPT state. This method may be called on a cipher in any state. Any state information (key, feedback buffer, ...) is lost and reset.
  Parameters:
    `key` - the key to use for decryption.
  Throws:
    NullPointerException - if key == null
    KeyException - if the key is invalid.

### update

    public final byte[] update(byte[] in)

  Encrypts or decrypts the specified array of data, which is not the final data in this stream. For block ciphers, if the last block so far is incomplete, it will be buffered and processed in subsequent calls to `update` or `crypt`.

  Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.

  This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for `javax.crypto.Cipher`.

  Parameters:
    `in` - the input data.
  Returns:
    the encryption or decryption result.
  Throws:
    NullPointerException - if in == null

### update

    public final byte[] update(byte[] in,
                               int offset,
                               int length)

  Encrypts or decrypts the specified subarray of data, which is not the final data in this stream. For block ciphers, if the last block so far is incomplete, it will be buffered and processed in subsequent calls to `update` or `crypt`.

  Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.

  This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for `javax.crypto.Cipher`.

  Parameters:
    `in` - the input data.
    `offset` - the offset indicating where the subarray starts in the in array.
    `length` - the length of the subarray.
  Returns:
    the encryption or decryption result.
  Throws:
    NullPointerException - if in == null
    IllegalArgumentException - if length < 0
    ArrayIndexOutOfBoundsException - if offset < 0 || (long) offset + length > in.length

### update

    public final int update(byte[] in,
                            int inOffset,
                            int inLen,
                            byte[] out)

  Encrypts or decrypts the specified subarray of data, which is not the final data in this stream, and places the result in the specified output buffer (starting at offset 0). For block ciphers, if the last block so far is incomplete, it will be buffered and processed in subsequent calls to `update` or `crypt`.

  Whether the data is encrypted or decrypted depends on the cipher's initialization state. `out.length` must be at least `outBufferSize(inLen)`, otherwise an ArrayIndexOutOfBoundsException will be thrown (in this case it is not specified how much, if any, of the output will have been written).

  This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for `javax.crypto.Cipher`.

  Parameters:
    `in` - the input data.
    `inOffset` - the offset indicating where the subarray starts in the in array.
    `inLen` - the length of the subarray.
    `out` - the output buffer.
  Returns:
    the number of bytes written.
  Throws:
    NullPointerException - if in == null || out == null
    IllegalArgumentException - if inLen < 0
    ArrayIndexOutOfBoundsException - if inOffset < 0 || outOffset < 0 || (long) inOffset + inLen > in.length || outBufferSize(inLen) > out.length

### update

    public final int update(byte[] in,
                            int inOffset,
                            int inLen,
                            byte[] out,
                            int outOffset)

  Encrypts or decrypts the specified subarray of data, which is not the final data in this stream, and places the result in the specified output buffer. For block ciphers, if the last block so far is incomplete, it will be buffered and processed in subsequent calls to `update` or `crypt`.

  Whether the data is encrypted or decrypted depends on the cipher's initialization state. `out.length` must be at least `(long) outOffset + outBufferSize(inLen)`, otherwise an ArrayIndexOutOfBoundsException will be thrown (in this case it is not specified how much, if any, of the output will have been written).

  This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for `javax.crypto.Cipher`.

  Parameters:
    `in` - the input data.
    `inOffset` - the offset indicating where the subarray starts in the in array.
    `inLen` - the length of the subarray.
    `out` - the output buffer.
    `outOffset` - the offset indicating where to start writing the result into the output buffer.
  Returns:
    the number of bytes written.
  Throws:
    NullPointerException - if in == null || out == null
    IllegalArgumentException - if inLen < 0
    ArrayIndexOutOfBoundsException - if inOffset < 0 || outOffset < 0 || (long) inOffset + inLen > in.length || (long) outOffset + outBufferSize(inLen) > out.length

### crypt

    public final byte[] crypt(byte[] in)
                       throws IllegalBlockSizeException

  Encrypts or decrypts the specified array of data, which will be automatically padded/unpadded as necessary.

  Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.

  If the final block is incomplete, the cipher must have a padding scheme other than "NONE", and it must be in the ENCRYPT state. If this is not the case, an IllegalBlockSizeException will be thrown.

  If the cipher is in the DECRYPT state and padding is being used, at least one full ciphertext block should be passed to `crypt`. This is necessary because the last block contains information needed to determine the length of the original plaintext.

  Parameters:
    `in` - the input data.
  Returns:
    the encryption or decryption result.
  Throws:
    NullPointerException - if in == null
    IllegalBlockSizeException - if the final block cannot be padded or unpadded.

### crypt

    public final byte[] crypt(byte[] in,
                              int offset,
                              int length)
                       throws IllegalBlockSizeException

  Encrypts or decrypts the specified array of data, which will be automatically padded/unpadded as necessary.

  Whether the data is encrypted or decrypted depends on the cipher's initialization state. This method will automatically allocate an output buffer of the right size.

  If the final block is incomplete, the cipher must have a padding scheme other than "NONE", and it must be in the ENCRYPT state. If this is not the case, an IllegalBlockSizeException will be thrown.

  If the cipher is in the DECRYPT state and padding is being used, at least one full ciphertext block should be passed to `crypt`. This is necessary because the last block contains information needed to determine the length of the original plaintext.

  Parameters:
    `in` - the input data.
    `offset` - the offset indicating where the subarray starts in the in array.
    `length` - the length of the subarray.
  Returns:
    the encryption or decryption result.
  Throws:
    NullPointerException - if in == null
    IllegalArgumentException - if length < 0
    ArrayIndexOutOfBoundsException - if offset < 0 || (long) offset + length > in.length
    IllegalBlockSizeException - if the final block cannot be padded or unpadded.

### crypt

    public final int crypt(byte[] in,
                           int inOffset,
                           int inLen,
                           byte[] out,
                           int outOffset)
                    throws IllegalBlockSizeException

  Encrypts or decrypts the specified subarray of data, pads or unpads it as necessary, and places the result in the specified output buffer.

  Whether the data is encrypted or decrypted depends on the cipher's initialization state.

  If the final block is incomplete, the cipher must have a padding scheme other than "NONE", and it must be in the ENCRYPT state. If this is not the case, an IllegalBlockSizeException will be thrown.

  If the cipher is in the DECRYPT state and padding is being used, at least one full ciphertext block should be passed to `crypt`. This is necessary because the last block contains information needed to determine the length of the original plaintext.

  Parameters:
    `in` - the input data.
    `inOffset` - the offset indicating where the subarray starts in the in array.
    `inLen` - the length of the subarray.
    `out` - the output buffer.
    `outOffset` - the offset indicating where to start writing the result into the output buffer.
  Returns:
    the number of bytes written.
  Throws:
    NullPointerException - if in == null || out == null
    IllegalArgumentException - if inLen < 0
    ArrayIndexOutOfBoundsException - if inOffset < 0 || outOffset < 0 || (long) inOffset + inLen > in.length || (long) outOffset + outBufferSize(inLen) > out.length

### doFinal

    public final byte[] doFinal(byte[] in)
                         throws IllegalBlockSizeException

  Equivalent to `crypt(in)`.

  This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for `javax.crypto.Cipher`.

### doFinal

    public final byte[] doFinal(byte[] in,
                                int offset,
                                int length)
                         throws IllegalBlockSizeException

  Equivalent to `crypt(in, offset, length)`.

  This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for `javax.crypto.Cipher`.

### doFinal

    public final int doFinal(byte[] in,
                             int inOffset,
                             int inLen,
                             byte[] out)
                      throws IllegalBlockSizeException

  Equivalent to `crypt(in, inOffset, inLen, out, 0)`.

  This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for `javax.crypto.Cipher`.

### doFinal

    public final int doFinal(byte[] in,
                             int inOffset,
                             int inLen,
                             byte[] out,
                             int outOffset)
                      throws IllegalBlockSizeException

  Equivalent to `crypt(in, inOffset, inLen, out, outOffset)`.

  This method is not supported in JavaSoft's version of JCE. However, an equivalent method is declared in the JCE 1.2 preview documentation for `javax.crypto.Cipher`.

### setParameter

    public void setParameter(String param,
                             Object value)
                      throws NoSuchParameterException,
                             InvalidParameterException,
                             InvalidParameterTypeException

  Sets the specified algorithm parameter to the specified value.

  This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as block size, a source of random bits for IV generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

  This method is not supported in JavaSoft's version of JCE.

  Specified by:
    setParameter in interface Parameterized
  Parameters:
    `param` - the string identifier of the parameter.
    `value` - the parameter value.
  Throws:
    NullPointerException - if param == null
    NoSuchParameterException - if there is no parameter with name param for this cipher implementation.
    InvalidParameterException - if the parameter exists but cannot be set (for example because the cipher is in the wrong state).
    InvalidParameterTypeException - if value is the wrong type for this parameter.

### getParameter

    public Object getParameter(String param)
                        throws NoSuchParameterException,
                               InvalidParameterException

  Gets the value of the specified algorithm parameter.

  This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as block size, a source of random bits for IV generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

  This method is not supported in JavaSoft's version of JCE.

  Specified by:
    getParameter in interface Parameterized
  Parameters:
    `param` - the string name of the parameter.
  Returns:
    the object that represents the parameter value.
  Throws:
    NullPointerException - if param == null
    NoSuchParameterException - if there is no parameter with name param for this cipher implementation.
    InvalidParameterException - if the parameter exists but cannot be read.

### clone

    public Object clone()
                 throws CloneNotSupportedException

  Returns a clone of this cipher.

  Note: In JavaSoft's version of JCE, `Cipher.clone()` is protected. This is not very useful, since then an application (as opposed to the cipher implementation itself) is not able to call it.

  Overrides:
    clone in class Object
  Throws:
    CloneNotSupportedException - if the cipher is not cloneable.

### toString

    public String toString()

  Overrides:
    toString in class Object

### engineSetPaddingScheme

    protected void engineSetPaddingScheme(PaddingScheme padding)

  SPI: Sets the object that will implement padding for this cipher.

  Cipher implementations may override this method in order to be notified when the padding scheme is set (in this case they should always call `super.engineSetPaddingScheme(padding)`). Normally, overriding this method is not required.

  Throws:
    IllegalStateException - if the cipher is already initialized.

### engineBlockSize

    protected int engineBlockSize()

  SPI: Returns the length of a block, in bytes. Ciphers for which plaintext and ciphertext blocks are the same size may override this method. Otherwise, both enginePlaintextBlockSize and engineCiphertextBlockSize should be overridden.

  The value may change when `initEncrypt` or `initDecrypt` is called, but it should not change at other times.

  Returns:
    the length in bytes of a block for this cipher.

### enginePlaintextBlockSize

    protected int enginePlaintextBlockSize()

  SPI: Returns the length of a plaintext block, in bytes. For byte-oriented stream ciphers, this method should return 1.

  The value may change when `initEncrypt` or `initDecrypt` is called, but it should not change at other times.

  The default implementation returns `engineBlockSize()`.

  Returns:
    the length in bytes of a plaintext block for this cipher.

### engineCiphertextBlockSize

    protected int engineCiphertextBlockSize()

  SPI: Returns the length of a ciphertext block, in bytes. For byte-oriented stream ciphers, this method should return 1.

  The value may change when `initEncrypt` or `initDecrypt` is called, but it should not change at other times.

  The default implementation returns `engineBlockSize()`.

  Returns:
    the length in bytes of a ciphertext block for this cipher.

### engineOutBufferSize

    protected int engineOutBufferSize(int inLen,
                                      boolean isFinal)

  SPI: Returns the length of output buffer required for a given length of input, in bytes. `isFinal` is true when this is the final block of input.

  If `implBuffering` is false, the `inLen` parameter already takes into account the length of any required padding, and buffered data. In this case `inLen` will be a multiple of the input block size (this may only be true for IJCE, not for other implementations of JCE).

  The default implementation assumes that the output will have the same number of blocks as the input (i.e. the result is `inLen / getInputBlockSize() * getOutputBlockSize()`).

  You will need to override this method if the cipher handles its own buffering.

  Parameters:
    `inLen` - the number of bytes of input
    `isFinal` - whether the last block is to be padded
  Returns:
    the length in bytes of the output block

### engineInBufferSize

    protected int engineInBufferSize(int outLen,
                                     boolean isFinal)

  SPI: Returns the minimum number of bytes of input, that will cause an output of outLen bytes from a call to `engineUpdate` (when isFinal is false), or successive calls to both `engineUpdate` and `engineCrypt` (when isFinal is true).

  If `implBuffering` is false, this method need not take into account padding or buffered data when calculating the result. In this case `outLen` will be a multiple of the output block size (this may only be true for IJCE, not for other implementations of JCE).

  The default implementation assumes that the output will have the same number of blocks as the input (i.e. the result is `outLen / getOutputBlockSize() * getInputBlockSize()`).

  You will need to override this method if the cipher handles its own buffering.

  Parameters:
    `outLen` - the number of bytes of output
    `isFinal` - whether the input includes the last block
  Returns:
    the length in bytes of the output block

### engineInitEncrypt

    protected abstract void engineInitEncrypt(Key key)
                                       throws KeyException

  SPI: Initializes this cipher for encryption, using the specified key.

  After a call to this method, the cipher's state is set to ENCRYPT.

  Parameters:
    `key` - the key to use for encryption.
  Throws:
    KeyException - if the key is invalid.

### engineInitDecrypt

    protected abstract void engineInitDecrypt(Key key)
                                       throws KeyException

  SPI: Initializes this cipher for decryption, using the specified key.

  After a call to this method, the cipher's state is set to DECRYPT.

  Parameters:
    `key` - the key to use for decryption.
  Throws:
    KeyException - if the key is invalid.

### engineUpdate

    protected abstract int engineUpdate(byte[] in,
                                        int inOffset,
                                        int inLen,
                                        byte[] out,
                                        int outOffset)

  SPI: This is the main engine method for updating data.

  When `implBuffering` is true, this method will be called with the same data that is passed to `update` or `crypt` (i.e. there will be exactly one call to `engineUpdate` for each call to `update` or `crypt`).

  When `implBuffering` is false, the Cipher superclass will ensure that when it calls this method, inLen is a non-negative multiple of `getInputBlockSize()`.

  in and out may be the same array, and the input and output regions may overlap. A cipher implementation should not use any part of in or out as working storage for intermediate steps of the algorithm. It should copy only the final result into the out array.

  SECURITY: if array arguments are passed to native code, the implementation must ensure that a buffer overflow or illegal memory access cannot occur, regardless of the arguments passed to this method. I.e. the native library should not be called if:

         in == null || out == null || inLen < 0 || inLen % (block size) != 0 ||
         inOffset < 0 || (long)inOffset + inLen > in.length ||
         outOffset < 0 || (long)outOffset + (number of bytes to be written) > out.length

  Note that the `(long)` casts are essential, because inOffset or outOffset could be close to `Integer.MAX_VALUE`. The native method being called should be private. This is important because untrusted code could subclass the cipher implementation, and call this method directly with any arguments.

  Parameters:
    `in` - the input data.
    `inOffset` - the offset into in specifying where the data starts.
    `inLen` - the length of the subarray.
    `out` - the output array.
    `outOffset` - the offset indicating where to start writing into the out array.
  Returns:
    the number of bytes written.

### engineCrypt

    protected int engineCrypt(byte[] out,
                              int outOffset)

  SPI: Process data buffered by this cipher implementation.

  This method is overriden by ciphers that handle their own buffering (i.e. `implBuffering == true`). It should flush the internal buffer, and process any remaining data. By default, this method returns 0.

  Ciphers that pass `implBuffering == false` to the superclass constructor need not override this method.

  SECURITY: if array arguments are passed to native code, the implementation must ensure that a buffer overflow or illegal memory access cannot occur, regardless of the arguments passed to this method. I.e. the native library should not be called if:

         out == null || outOffset < 0 ||
         (long)outOffset + (number of bytes to be written) > out.length

  Note that the `(long)` cast is essential, because outOffset could be close to `Integer.MAX_VALUE`. The native method being called should be private. This is important because untrusted code could subclass the cipher implementation, and call this method directly with any arguments.

  Parameters:
    `out` - the output buffer into which to write the result.
  Returns:
    the number of bytes written.

### engineSetParameter

    protected void engineSetParameter(String param,
                                      Object value)
                               throws NoSuchParameterException,
                                      InvalidParameterException,
                                      InvalidParameterTypeException

  SPI: Sets the specified algorithm parameter to the specified value.

  This method supplies a general-purpose mechanism through which it is possible to set the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as block size, a source of random bits for IV generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

  The default implementation always throws a NoSuchParameterException.

  This method is not supported in JavaSoft's version of JCE.

  Parameters:
    `param` - the string name of the parameter.
    `value` - the parameter value.
  Throws:
    NoSuchParameterException - if there is no parameter with name param for this cipher implementation.
    InvalidParameterException - if the parameter exists but cannot be set (for example because the cipher is in the wrong state).
    InvalidParameterTypeException - if value is the wrong type for this parameter.

### engineGetParameter

    protected Object engineGetParameter(String param)
                                 throws NoSuchParameterException,
                                        InvalidParameterException

  SPI: Gets the value of the specified algorithm parameter.

  This method supplies a general-purpose mechanism through which it is possible to get the various parameters of this object. A parameter may be any settable parameter for the algorithm, such as block size, a source of random bits for IV generation (if appropriate), or an indication of whether or not to perform a specific but optional computation. A uniform algorithm-specific naming scheme for each parameter is desirable but left unspecified at this time.

  The default implementation always throws a NoSuchParameterException.

  This method is not supported in JavaSoft's version of JCE.

  Parameters:
    `param` - the string name of the parameter.
  Returns:
    the object that represents the parameter value.
  Throws:
    NoSuchParameterException - if there is no parameter with name param for this cipher implementation.
    InvalidParameterException - if the parameter exists but cannot be read.

### getAlgorithms

    public static String[] getAlgorithms(Provider provider)

  Gets the standard names of all Ciphers implemented by a provider.

  This method is not supported in JavaSoft's version of JCE. For compatibility you may wish to use `IJCE.getAlgorithms(provider, "Cipher")` instead.

  Since:
    IJCE 1.0.1

### getAlgorithms

    public static String[] getAlgorithms()

  Gets the standard names of all Ciphers implemented by any installed provider. Algorithm names are not duplicated if they are supported by more than one provider (but specialized cipher/mode implementations are treated as distinct, for example "DES/CBC" is different from "DES").

  This method is not supported in JavaSoft's version of JCE. For compatibility you may wish to use `IJCE.getAlgorithms("Cipher")` instead.

  Since:
    IJCE 1.0.1

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
| Cryptix V3.1
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright (C) 1995-2000 The Cryptix Foundation Ltd. All rights reserved.