https://openjdk.java.net/ 
/*
 * Copyright (c) 1997, 2020, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code 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
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.crypto;

import java.io.InputStream;
import java.io.FilterInputStream;
import java.io.IOException;
import javax.crypto.BadPaddingException;
import javax.crypto.IllegalBlockSizeException;


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 class adheres strictly to the semantics, especially the
failure semantics, of its ancestor classes
java.io.FilterInputStream and java.io.InputStream.  This class has
exactly those methods specified in its ancestor classes, and
overrides them all.  Moreover, this class catches all exceptions
that are not thrown by its ancestor classes.  In particular, the
skip method skips, and the available
method counts only data that have been processed by the encapsulated Cipher.
This class may catch BadPaddingException and other exceptions thrown by
failed integrity checks during decryption. These exceptions are not
re-thrown, so the client may not be informed that integrity checks
failed. Because of this behavior, this class may not be suitable
for use with decryption in an authenticated mode of operation (e.g. GCM).
Applications that require authenticated encryption can use the Cipher API
directly as an alternative to using this class.

 It is crucial for a programmer using this class not to use
methods that are not defined or overridden in this class (such as a
new method or constructor that is later added to one of the super
classes), because the design and implementation of those methods
are unlikely to have considered security impact with regard to
CipherInputStream.

Author: Li Gong
See Also:
Since:1.4
/**
 * 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.
 *
 * <p> 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.
 *
 * <p> This class adheres strictly to the semantics, especially the
 * failure semantics, of its ancestor classes
 * java.io.FilterInputStream and java.io.InputStream.  This class has
 * exactly those methods specified in its ancestor classes, and
 * overrides them all.  Moreover, this class catches all exceptions
 * that are not thrown by its ancestor classes.  In particular, the
 * <code>skip</code> method skips, and the <code>available</code>
 * method counts only data that have been processed by the encapsulated Cipher.
 * This class may catch BadPaddingException and other exceptions thrown by
 * failed integrity checks during decryption. These exceptions are not
 * re-thrown, so the client may not be informed that integrity checks
 * failed. Because of this behavior, this class may not be suitable
 * for use with decryption in an authenticated mode of operation (e.g. GCM).
 * Applications that require authenticated encryption can use the Cipher API
 * directly as an alternative to using this class.
 *
 * <p> It is crucial for a programmer using this class not to use
 * methods that are not defined or overridden in this class (such as a
 * new method or constructor that is later added to one of the super
 * classes), because the design and implementation of those methods
 * are unlikely to have considered security impact with regard to
 * CipherInputStream.
 *
 * @author  Li Gong
 * @see     java.io.InputStream
 * @see     java.io.FilterInputStream
 * @see     javax.crypto.Cipher
 * @see     javax.crypto.CipherOutputStream
 *
 * @since 1.4
 */

public class CipherInputStream extends FilterInputStream {

    // the cipher engine to use to process stream data
    private Cipher cipher;

    // the underlying input stream
    private InputStream input;

    /* the buffer holding data that have been read in from the
       underlying stream, but have not been processed by the cipher
       engine. the size 512 bytes is somewhat randomly chosen */
    private byte[] ibuffer = new byte[512];

    // having reached the end of the underlying input stream
    private boolean done = false;

    /* the buffer holding data that have been processed by the cipher
       engine, but have not been read out */
    private byte[] obuffer = null;
    // the offset pointing to the next "new" byte
    private int ostart = 0;
    // the offset pointing to the last "new" byte
    private int ofinish = 0;
    // stream status
    private boolean closed = false;

    
Ensure obuffer is big enough for the next update or doFinal
operation, given the input length inLen (in bytes)
The ostart and ofinish indices are reset to 0.

Params:
  • inLen – the input length (in bytes)
/**
     * Ensure obuffer is big enough for the next update or doFinal
     * operation, given the input length <code>inLen</code> (in bytes)
     * The ostart and ofinish indices are reset to 0.
     *
     * @param inLen the input length (in bytes)
     */
    private void ensureCapacity(int inLen) {
        int minLen = cipher.getOutputSize(inLen);
        if (obuffer == null || obuffer.length < minLen) {
            obuffer = new byte[minLen];
        }
        ostart = 0;
        ofinish = 0;
    }

    
Private convenience function, read in data from the underlying
input stream and process them with cipher. This method is called
when the processed bytes inside obuffer has been exhausted.
Entry condition: ostart = ofinish
Exit condition: ostart = 0 AND ostart <= ofinish
return (ofinish-ostart) (we have this many bytes for you)
return 0 (no data now, but could have more later)
return -1 (absolutely no more data)
Note: Exceptions are only thrown after the stream is completely read.
For AEAD ciphers a read() of any length will internally cause the
whole stream to be read fully and verify the authentication tag before
returning decrypted data or exceptions.

/**
     * Private convenience function, read in data from the underlying
     * input stream and process them with cipher. This method is called
     * when the processed bytes inside obuffer has been exhausted.
     *
     * Entry condition: ostart = ofinish
     *
     * Exit condition: ostart = 0 AND ostart <= ofinish
     *
     * return (ofinish-ostart) (we have this many bytes for you)
     * return 0 (no data now, but could have more later)
     * return -1 (absolutely no more data)
     *
     * Note: Exceptions are only thrown after the stream is completely read.
     * For AEAD ciphers a read() of any length will internally cause the
     * whole stream to be read fully and verify the authentication tag before
     * returning decrypted data or exceptions.
     */
    private int getMoreData() throws IOException {
        if (done) return -1;
        int readin = input.read(ibuffer);

        if (readin == -1) {
            done = true;
            ensureCapacity(0);
            try {
                ofinish = cipher.doFinal(obuffer, 0);
            } catch (IllegalBlockSizeException | BadPaddingException
                    | ShortBufferException e) {
                throw new IOException(e);
            }
            if (ofinish == 0) {
                return -1;
            } else {
                return ofinish;
            }
        }
        ensureCapacity(readin);
        try {
            ofinish = cipher.update(ibuffer, 0, readin, obuffer, ostart);
        } catch (IllegalStateException e) {
            throw e;
        } catch (ShortBufferException e) {
            throw new IOException(e);
        }
        return ofinish;
    }

    
Constructs a CipherInputStream from an InputStream and a
Cipher.

Note: if the specified input stream or cipher is
null, a NullPointerException may be thrown later when
they are used.

Params:
  • is – the to-be-processed input stream
  • c – an initialized Cipher object
/**
     * Constructs a CipherInputStream from an InputStream and a
     * Cipher.
     * <br>Note: if the specified input stream or cipher is
     * null, a NullPointerException may be thrown later when
     * they are used.
     * @param is the to-be-processed input stream
     * @param c an initialized Cipher object
     */
    public CipherInputStream(InputStream is, Cipher c) {
        super(is);
        input = is;
        cipher = c;
    }

    
Constructs a CipherInputStream from an InputStream without
specifying a Cipher. This has the effect of constructing a
CipherInputStream using a NullCipher.

Note: if the specified input stream is null, a
NullPointerException may be thrown later when it is used.

Params:
  • is – the to-be-processed input stream
/**
     * Constructs a CipherInputStream from an InputStream without
     * specifying a Cipher. This has the effect of constructing a
     * CipherInputStream using a NullCipher.
     * <br>Note: if the specified input stream is null, a
     * NullPointerException may be thrown later when it is used.
     * @param is the to-be-processed input stream
     */
    protected CipherInputStream(InputStream is) {
        super(is);
        input = is;
        cipher = new NullCipher();
    }

    
Reads the next byte of data from this input stream. The value
byte is returned as an int in the range
0 to 255. If no byte is available
because the end of the stream has been reached, the value
-1 is returned. This method blocks until input data
is available, the end of the stream is detected, or an exception
is thrown.

Throws:
Returns: the next byte of data, or -1 if the end of the
         stream is reached.
/**
     * Reads the next byte of data from this input stream. The value
     * byte is returned as an <code>int</code> in the range
     * <code>0</code> to <code>255</code>. If no byte is available
     * because the end of the stream has been reached, the value
     * <code>-1</code> is returned. This method blocks until input data
     * is available, the end of the stream is detected, or an exception
     * is thrown.
     *
     * @return  the next byte of data, or <code>-1</code> if the end of the
     *          stream is reached.
     * @exception  IOException  if an I/O error occurs.
     */
    @Override
    public int read() throws IOException {
        if (ostart >= ofinish) {
            // we loop for new data as the spec says we are blocking
            int i = 0;
            while (i == 0) i = getMoreData();
            if (i == -1) return -1;
        }
        return ((int) obuffer[ostart++] & 0xff);
    };

    
Reads up to b.length bytes of data from this input
stream into an array of bytes.


The read method of InputStream calls
the read method of three arguments with the arguments
b, 0, and b.length.

Params:
  • b –   the buffer into which the data is read.
Throws:
See Also:
Returns:    the total number of bytes read into the buffer, or
            -1 is there is no more data because the end of
            the stream has been reached.
/**
     * Reads up to <code>b.length</code> bytes of data from this input
     * stream into an array of bytes.
     * <p>
     * The <code>read</code> method of <code>InputStream</code> calls
     * the <code>read</code> method of three arguments with the arguments
     * <code>b</code>, <code>0</code>, and <code>b.length</code>.
     *
     * @param      b   the buffer into which the data is read.
     * @return     the total number of bytes read into the buffer, or
     *             <code>-1</code> is there is no more data because the end of
     *             the stream has been reached.
     * @exception  IOException  if an I/O error occurs.
     * @see        java.io.InputStream#read(byte[], int, int)
     */
    @Override
    public int read(byte b[]) throws IOException {
        return read(b, 0, b.length);
    }

    
Reads up to len bytes of data from this input stream
into an array of bytes. This method blocks until some input is
available. If the first argument is null, up to
len bytes are read and discarded.

Params:
  • b –     the buffer into which the data is read.
  • off –   the start offset in the destination array
                  buf
  • len –   the maximum number of bytes read.
Throws:
See Also:
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.
/**
     * Reads up to <code>len</code> bytes of data from this input stream
     * into an array of bytes. This method blocks until some input is
     * available. If the first argument is <code>null,</code> up to
     * <code>len</code> bytes are read and discarded.
     *
     * @param      b     the buffer into which the data is read.
     * @param      off   the start offset in the destination array
     *                   <code>buf</code>
     * @param      len   the maximum number of bytes read.
     * @return     the total number of bytes read into the buffer, or
     *             <code>-1</code> if there is no more data because the end of
     *             the stream has been reached.
     * @exception  IOException  if an I/O error occurs.
     * @see        java.io.InputStream#read()
     */
    @Override
    public int read(byte b[], int off, int len) throws IOException {
        if (ostart >= ofinish) {
            // we loop for new data as the spec says we are blocking
            int i = 0;
            while (i == 0) i = getMoreData();
            if (i == -1) return -1;
        }
        if (len <= 0) {
            return 0;
        }
        int available = ofinish - ostart;
        if (len < available) available = len;
        if (b != null) {
            System.arraycopy(obuffer, ostart, b, off, available);
        }
        ostart = ostart + available;
        return available;
    }

    
Skips n bytes of input from the bytes that can be read
from this input stream without blocking.

Fewer bytes than requested might be skipped.
The actual number of bytes skipped is equal to n or the result of a call to available, whichever is smaller. If n is less than zero, no bytes are skipped.

The actual number of bytes skipped is returned.

Params:
  • n – the number of bytes to be skipped.
Throws:
Returns:    the actual number of bytes skipped.
/**
     * Skips <code>n</code> bytes of input from the bytes that can be read
     * from this input stream without blocking.
     *
     * <p>Fewer bytes than requested might be skipped.
     * The actual number of bytes skipped is equal to <code>n</code> or
     * the result of a call to
     * {@link #available() available},
     * whichever is smaller.
     * If <code>n</code> is less than zero, no bytes are skipped.
     *
     * <p>The actual number of bytes skipped is returned.
     *
     * @param      n the number of bytes to be skipped.
     * @return     the actual number of bytes skipped.
     * @exception  IOException  if an I/O error occurs.
     */
    @Override
    public long skip(long n) throws IOException {
        int available = ofinish - ostart;
        if (n > available) {
            n = available;
        }
        if (n < 0) {
            return 0;
        }
        ostart += n;
        return n;
    }

    
Returns the number of bytes that can be read from this input
stream without blocking. The available method of
InputStream returns 0. This method
should be overridden by subclasses.

Throws:
Returns:    the number of bytes that can be read from this input stream
            without blocking.
/**
     * Returns the number of bytes that can be read from this input
     * stream without blocking. The <code>available</code> method of
     * <code>InputStream</code> returns <code>0</code>. This method
     * <B>should</B> be overridden by subclasses.
     *
     * @return     the number of bytes that can be read from this input stream
     *             without blocking.
     * @exception  IOException  if an I/O error occurs.
     */
    @Override
    public int available() throws IOException {
        return (ofinish - ostart);
    }

    
Closes this input stream and releases any system resources
associated with the stream.


The close method of CipherInputStream
calls the close method of its underlying input
stream.

Throws:
  • IOException –  if an I/O error occurs.
/**
     * Closes this input stream and releases any system resources
     * associated with the stream.
     * <p>
     * The <code>close</code> method of <code>CipherInputStream</code>
     * calls the <code>close</code> method of its underlying input
     * stream.
     *
     * @exception  IOException  if an I/O error occurs.
     */
    @Override
    public void close() throws IOException {
        if (closed) {
            return;
        }
        closed = true;
        input.close();

        // Throw away the unprocessed data and throw no crypto exceptions.
        // AEAD ciphers are fully readed before closing.  Any authentication
        // exceptions would occur while reading.
        if (!done) {
            ensureCapacity(0);
            try {
                cipher.doFinal(obuffer, 0);
            } catch (BadPaddingException | IllegalBlockSizeException
                    | ShortBufferException ex) {
                // Catch exceptions as the rest of the stream is unused.
            }
        }
        obuffer = null;
    }

    
Tests if this input stream supports the mark
and reset methods, which it does not.

See Also:
Returns: false, since this class does not support the
         mark and reset methods.
/**
     * Tests if this input stream supports the <code>mark</code>
     * and <code>reset</code> methods, which it does not.
     *
     * @return  <code>false</code>, since this class does not support the
     *          <code>mark</code> and <code>reset</code> methods.
     * @see     java.io.InputStream#mark(int)
     * @see     java.io.InputStream#reset()
     */
    @Override
    public boolean markSupported() {
        return false;
    }
}