CipherInputStream (Bouncy Castle Library 1.52 API Specification)
Date: 2015-03-01

org.bouncycastle.jcajce.io

## Class CipherInputStream

- java.lang.Object
- - java.io.InputStream
  - - java.io.FilterInputStream
    - - org.bouncycastle.jcajce.io.CipherInputStream

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable

      public class CipherInputStream
      extends java.io.FilterInputStream

  A CipherInputStream is composed of an InputStream and a cipher so that read() methods return data that are read in from the underlying InputStream but have been additionally processed by the Cipher. The cipher must be fully initialized before being used by a CipherInputStream.

  For example, if the Cipher is initialized for decryption, the CipherInputStream will attempt to read in data and decrypt them, before returning the decrypted data.

  This is a reimplementation of `CipherInputStream` that is safe for use with AEAD block ciphers, and does not silently catch `BadPaddingException` and `IllegalBlockSizeException` errors. Any errors that occur during `finalisation` are rethrown wrapped in an `InvalidCipherTextIOException`.

- - ### Field Summary

    - ### Fields inherited from class java.io.FilterInputStream

      `in`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CipherInputStream(java.io.InputStream input, javax.crypto.Cipher cipher)` Constructs a CipherInputStream from an InputStream and an initialised Cipher.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `available()`
    `void` | `close()` Closes the underlying input stream, and then finalises the processing of the data by the cipher.
    `void` | `mark(int readlimit)`
    `boolean` | `markSupported()`
    `int` | `read()` Reads data from the underlying stream and processes it with the cipher until the cipher outputs data, and returns the next available byte.
    `int` | `read(byte[] b, int off, int len)` Reads data from the underlying stream and processes it with the cipher until the cipher outputs data, and then returns up to `len` bytes in the provided array.
    `void` | `reset()`
    `long` | `skip(long n)`

    - ### Methods inherited from class java.io.FilterInputStream

      `read`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### CipherInputStream

          public CipherInputStream(java.io.InputStream input,
                           javax.crypto.Cipher cipher)

      Constructs a CipherInputStream from an InputStream and an initialised Cipher.

  - ### Method Detail

    - #### read

          public int read()
                   throws java.io.IOException

      Reads data from the underlying stream and processes it with the cipher until the cipher outputs data, and returns the next available byte.

      If the underlying stream is exhausted by this call, the cipher will be finalised.

      Overrides:
        `read` in class `java.io.FilterInputStream`
      Throws:
        `java.io.IOException` - if there was an error closing the input stream.
        `InvalidCipherTextIOException` - if the data read from the stream was invalid ciphertext (e.g. the cipher is an AEAD cipher and the ciphertext tag check fails).

    - #### read

          public int read(byte[] b,
                 int off,
                 int len)
                   throws java.io.IOException

      Reads data from the underlying stream and processes it with the cipher until the cipher outputs data, and then returns up to `len` bytes in the provided array.

      If the underlying stream is exhausted by this call, the cipher will be finalised.

      Overrides:
        `read` in class `java.io.FilterInputStream`
      Parameters:
        `b` - the buffer into which the data is read.
        `off` - the start offset in the destination array `b`
        `len` - the maximum number of bytes read.
      Returns:
        the total number of bytes read into the buffer, or `-1` if there is no more data because the end of the stream has been reached.
      Throws:
        `java.io.IOException` - if there was an error closing the input stream.
        `InvalidCipherTextIOException` - if the data read from the stream was invalid ciphertext (e.g. the cipher is an AEAD cipher and the ciphertext tag check fails).

    - #### skip

          public long skip(long n)
                    throws java.io.IOException

      Overrides:
        `skip` in class `java.io.FilterInputStream`
      Throws:
        `java.io.IOException`

    - #### available

          public int available()
                        throws java.io.IOException

      Overrides:
        `available` in class `java.io.FilterInputStream`
      Throws:
        `java.io.IOException`

    - #### close

          public void close()
                     throws java.io.IOException

      Closes the underlying input stream, and then finalises the processing of the data by the cipher.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`
      Overrides:
        `close` in class `java.io.FilterInputStream`
      Throws:
        `java.io.IOException` - if there was an error closing the input stream.
        `InvalidCipherTextIOException` - if the data read from the stream was invalid ciphertext (e.g. the cipher is an AEAD cipher and the ciphertext tag check fails).

    - #### mark

          public void mark(int readlimit)

      Overrides:
        `mark` in class `java.io.FilterInputStream`

    - #### reset

          public void reset()
                     throws java.io.IOException

      Overrides:
        `reset` in class `java.io.FilterInputStream`
      Throws:
        `java.io.IOException`

    - #### markSupported

          public boolean markSupported()

      Overrides:
        `markSupported` in class `java.io.FilterInputStream`