OpenJDK 27 · javax.crypto.CipherInputStream · APIdia, the JavaDoc alternative

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

For example, if the Cipher object 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 object. 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.

Field Summary

Modifier and Type	Field and Description
private final Cipher	cipher
private boolean	closed
private boolean	done
private final byte[]	ibuffer
private final InputStream	input
private byte[]	obuffer
private int	ofinish
private int	ostart

Inherited from java.io.FilterInputStream:: in

Constructor Summary

Access	Constructor and Description
public	CipherInputStream(InputStream the to-be-processed input stream is, Cipher an initialized `Cipher` object c) Constructs a `CipherInputStream` from an `InputStream` and a `Cipher` object.
protected	CipherInputStream(InputStream the to-be-processed input stream is) Constructs a `CipherInputStream` from an `InputStream` without specifying a `Cipher` object.

Method Summary

Modifier and Type	Method and Description
public int	Returns: the number of bytes that can be read from this input stream without blocking. available() Overrides java.io.FilterInputStream.available. Returns the number of bytes that can be read from this input stream without blocking.
public void	close() Overrides java.io.FilterInputStream.close. Implements java.io.Closeable.close. Closes this input stream and releases any system resources associated with the stream.
private void	ensureCapacity(int the input length (in bytes) inLen) 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.
private int	getMoreData() Private convenience function, read in data from the underlying input stream and process them with cipher.
public boolean	Returns: `false`, since this class does not support the `mark` and `reset` methods. markSupported() Overrides java.io.FilterInputStream.markSupported. Tests if this input stream supports the `mark` and `reset` methods, which it does not.
public int	Returns: the next byte of data, or `-1` if the end of the stream is reached. read() Overrides java.io.FilterInputStream.read. Reads the next byte of data from this input stream.
public int	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. read(byte[] the buffer into which the data is read. b) Overrides java.io.FilterInputStream.read. Reads up to `b.length` bytes of data from this input stream into an array of bytes.
public int	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. read(byte[] the buffer into which the data is read. b, int the start offset in the destination array `buf` off, int the maximum number of bytes read. len) Overrides java.io.FilterInputStream.read. Reads up to `len` bytes of data from this input stream into an array of bytes.
public long	Returns: the actual number of bytes skipped. skip(long the number of bytes to be skipped. n) Overrides java.io.FilterInputStream.skip. Skips `n` bytes of input from the bytes that can be read from this input stream without blocking.

Inherited from java.io.FilterInputStream:: mark reset

Field Detail

cipher	back to summary
private final Cipher cipher

closed	back to summary
private boolean closed

done	back to summary
private boolean done

ibuffer	back to summary
private final byte[] ibuffer

input	back to summary
private final InputStream input

obuffer	back to summary
private byte[] obuffer

ofinish	back to summary
private int ofinish

ostart	back to summary
private int ostart

Constructor Detail

CipherInputStream back to summary

CipherInputStream	back to summary
public CipherInputStream(InputStream is, Cipher c) Constructs a `CipherInputStream` from an `InputStream` and a `Cipher` object. Note if the specified input stream or cipher is `null`, a `NullPointerException` may be thrown later when they are used. Parameters is:InputStream the to-be-processed input stream c:Cipher an initialized `Cipher` object

public CipherInputStream(InputStream is, Cipher c)

Constructs a CipherInputStream from an InputStream and a Cipher object.

Note

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

Parameters

is:InputStream: the to-be-processed input stream
c:Cipher: an initialized Cipher object

CipherInputStream back to summary

CipherInputStream	back to summary
protected CipherInputStream(InputStream is) Constructs a `CipherInputStream` from an `InputStream` without specifying a `Cipher` object. 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. Parameters is:InputStream the to-be-processed input stream

protected CipherInputStream(InputStream is)

Constructs a CipherInputStream from an InputStream without specifying a Cipher object. 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.

Parameters

is:InputStream: the to-be-processed input stream

Method Detail

available back to summary

available	back to summary
public int available() throws IOException Overrides java.io.FilterInputStream.available. 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. Returns:int the number of bytes that can be read from this input stream without blocking. Annotations @Override Exceptions IOException: if an I/O error occurs.

public int available() throws IOException

Overrides java.io.FilterInputStream.available.

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.

Returns:int

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

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

close back to summary

close	back to summary
public void close() throws IOException Overrides java.io.FilterInputStream.close. Implements java.io.Closeable.close. 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. Annotations @Override Exceptions IOException: if an I/O error occurs.

public void close() throws IOException

Overrides java.io.FilterInputStream.close.

Implements java.io.Closeable.close.

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.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

ensureCapacity back to summary

ensureCapacity	back to summary
private void ensureCapacity(int inLen) 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. If obuffer is null/zero-sized, do not allocate a new buffer. This reduces allocation for authenticated decryption that never returns data from update Parameters inLen:int the input length (in bytes)

private void ensureCapacity(int inLen)

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. If obuffer is null/zero-sized, do not allocate a new buffer. This reduces allocation for authenticated decryption that never returns data from update

Parameters

inLen:int: the input length (in bytes)

getMoreData	back to summary
private int getMoreData() throws IOException 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.

getMoreData

back to summary

private int getMoreData() throws IOException

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.

markSupported back to summary

markSupported	back to summary
public boolean markSupported() Overrides java.io.FilterInputStream.markSupported. Tests if this input stream supports the `mark` and `reset` methods, which it does not. Returns:boolean `false`, since this class does not support the `mark` and `reset` methods. Annotations @Override See Also `java.io.InputStream#mark(int)`, `java.io.InputStream#reset()`

public boolean markSupported()

Overrides java.io.FilterInputStream.markSupported.

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

Returns:boolean

false, since this class does not support the mark and reset methods.

Annotations

@Override

read back to summary

read	back to summary
public int read() throws IOException Overrides java.io.FilterInputStream.read. 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. Returns:int the next byte of data, or `-1` if the end of the stream is reached. Annotations @Override Exceptions IOException: if an I/O error occurs.

public int read() throws IOException

Overrides java.io.FilterInputStream.read.

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.

Returns:int

the next byte of data, or -1 if the end of the stream is reached.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

read back to summary

read	back to summary
public int read(byte[] b) throws IOException Overrides java.io.FilterInputStream.read. 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`. Parameters b:byte[] the buffer into which the data is read. Returns:int 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. Annotations @Override Exceptions IOException: if an I/O error occurs. See Also `java.io.InputStream#read(byte[], int, int)`

public int read(byte[] b) throws IOException

Overrides java.io.FilterInputStream.read.

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.

Parameters

b:byte[]: the buffer into which the data is read.

Returns:int

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.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

read back to summary

read	back to summary
public int read(byte[] b, int off, int len) throws IOException Overrides java.io.FilterInputStream.read. 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. Parameters b:byte[] the buffer into which the data is read. off:int the start offset in the destination array `buf` len:int the maximum number of bytes read. Returns:int 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. Annotations @Override Exceptions IOException: if an I/O error occurs. See Also `java.io.InputStream#read()`

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

Overrides java.io.FilterInputStream.read.

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.

Parameters

b:byte[]: the buffer into which the data is read.
off:int: the start offset in the destination array buf
len:int: the maximum number of bytes read.

Returns:int

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.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

See Also

java.io.InputStream#read()

skip back to summary

skip	back to summary
public long skip(long n) throws IOException Overrides java.io.FilterInputStream.skip. 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. Parameters n:long the number of bytes to be skipped. Returns:long the actual number of bytes skipped. Annotations @Override Exceptions IOException: if an I/O error occurs.

public long skip(long n) throws IOException

Overrides java.io.FilterInputStream.skip.

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.

Parameters

n:long: the number of bytes to be skipped.

Returns:long

the actual number of bytes skipped.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

public Class CipherInputStream

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail