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 CipherOutputStream

    java.lang.Object
      |
      +--java.io.OutputStream
            |
            +--java.io.FilterOutputStream
                  |
                  +--java.security.CipherOutputStream

public class CipherOutputStream
extends java.io.FilterOutputStream

A FilterOutputStream that encrypts or decrypts the data passing through it.

This class has a constructor that takes a Cipher and an output stream as arguments. The cipher is used to encrypt or decrypt all data supplied via calls to one of the `write` methods. The encryption/decryption result is written to the output stream.

For block ciphers, a buffer is used for receiving the data to be encrypted or decrypted. The maximum number of bytes that may be buffered at any given time is given by the `getBufferSize` method. For byte-oriented stream ciphers, no buffering is done (and `getBufferSize()` returns 0).

To supply the bytes that need to be encrypted/decrypted, make one or more calls to one of the `write` methods. After you have supplied all the data, call `close()` to ensure final processing is done.

Note: JavaSoft's JCE required calling `flush` for final processing, rather than `close`. However, if you call `flush` and then write more data, there will not be sufficient information available when reading in the stream (e.g. using `CipherInputStream`), to determine when the flush happened. Unpadding can only work correctly if no further data is written after the final processing, which means that `close` is the right method to trigger this processing. I'm not sure whether JavaSoft's implementation works if only `close` is called, but calling `flush` followed by `close` should work in both implementations.

With a cipher in the ENCRYPT state, the number of bytes not yet encrypted and written to the stream is kept between 0 and `cipher.getPlaintextBlockSize()-1` inclusive. When `close` is called, the final data is padded, encrypted, and the result written to the output stream. If the cipher's padding scheme is NONE and the final data does not comprise a complete plaintext block, an `IllegalBlockSizeException` is thrown.

With a cipher in the DECRYPT state, [DOCUMENT ME]. When `close` is called, an exact number of ciphertext blocks should be in the buffer (otherwise an `IllegalBlockSizeException` is thrown). Those blocks are decrypted, unpadded, and written to the output stream.

Note: calling methods of a cipher while it is being used by a CipherInputStream (apart from methods that have no side-effects, like `getAlgorithm()`, `get*BlockSize()`, etc.) will probably result in incorrect or unexpected output.

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

$Revision: 1.5 $

See Also:
  `Cipher`, `Cipher.getInputBlockSize()`, `Cipher.getOutputBlockSize()`, `CipherInputStream`

Fields inherited from class java.io.FilterOutputStream
`out`

Constructor Summary
`CipherOutputStream(java.io.OutputStream os, Cipher cipher)` Constructs an output stream using a cipher that must be initialized for either encryption or decryption, that is, a cipher whose state is either `ENCRYPT` or `DECRYPT`.

Method Summary
`void` | `close()` Closes the output stream.
`void` | `flush()` Flushes the underlying output stream.
`void` | `write(byte[] in, int offset, int length)` Supplies bytes to be used for encryption or decryption, depending on the cipher state.
`void` | `write(int b)` Supplies a byte to be used for encryption or decryption, depending on the cipher state.

Methods inherited from class java.io.FilterOutputStream
`write`

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

Constructor Detail

### CipherOutputStream

    public CipherOutputStream(java.io.OutputStream os,
                              Cipher cipher)

  Constructs an output stream using a cipher that must be initialized for either encryption or decryption, that is, a cipher whose state is either `ENCRYPT` or `DECRYPT`.
  Parameters:
    `os` - the output stream.
    `cipher` - an initialized cipher.
  Throws:
    NullPointerException - if os == null || cipher == null

Method Detail

### write

    public void write(byte[] in,
                      int offset,
                      int length)
               throws java.io.IOException

  Supplies bytes to be used for encryption or decryption, depending on the cipher state.
  Overrides:
    write in class java.io.FilterOutputStream
  Parameters:
    `in` - the buffer containing the bytes to be used for encryption or decryption.
    `offset` - the offset into in indicating the location of the first byte to be used.
    `length` - the number of bytes to read from in, starting at offset offset.
  Throws:
    ArrayIndexOutOfBoundsException - if (long)offset + length > in.length
    java.io.IOException - if an error occurs, or the stream has already been closed.

### write

    public void write(int b)
               throws java.io.IOException

  Supplies a byte to be used for encryption or decryption, depending on the cipher state.
  Overrides:
    write in class java.io.FilterOutputStream
  Parameters:
    `b` - the byte to be used for encryption or decryption.
  Throws:
    java.io.IOException - if an error occurs.

### flush

    public void flush()
               throws java.io.IOException

  Flushes the underlying output stream. Unlike JavaSoft's implementation, this never writes any further data to the stream. To make sure that all data has been written, call `close()`.
  Overrides:
    flush in class java.io.FilterOutputStream
  Throws:
    java.io.IOException - if an error occurs.

### close

    public void close()
               throws java.io.IOException

  Closes the output stream. Before it is closed, buffered data is processed, taking into account padding, and the result is written to the stream.

  For an encrypter stream, any buffered data is encrypted and the result written to the output stream. If the padding scheme is not "NONE", the data is padded before encryption. If the padding scheme is "NONE" and the final data does not comprise a complete block, an `IllegalBlockSize` exception is thrown.

  For a decrypter stream, when `close` is called, exactly one block should be in the buffer. It is decrypted, unpadded, and written out.

  Overrides:
    close in class java.io.FilterOutputStream
  Throws:
    java.io.IOException - if an error occurs.

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.