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

A CipherOutputStream is composed of an OutputStream and a Cipher object so that write() methods first process the data before writing them out to the underlying OutputStream. The Cipher object must be fully initialized before being used by a CipherOutputStream.

For example, if the Cipher object is initialized for encryption, the CipherOutputStream will attempt to encrypt data before writing out the encrypted data.

This class adheres strictly to the semantics, especially the failure semantics, of its ancestor classes java.io.OutputStream and java.io.FilterOutputStream. 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, this class catches BadPaddingException and other exceptions thrown by failed integrity checks during decryption. These exceptions are not re-thrown, so the client will 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) if the application requires explicit notification when authentication fails. Such an application 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 CipherOutputStream.

Field Summary

Modifier and Type	Field and Description
private final Cipher	cipher
private boolean	closed Hides java.io.FilterOutputStream.closed.
private final byte[]	ibuffer
private byte[]	obuffer
private final OutputStream	output

Inherited from java.io.FilterOutputStream:: out

Constructor Summary

Access	Constructor and Description
public	CipherOutputStream(OutputStream the `OutputStream` object os, Cipher an initialized `Cipher` object c) Constructs a `CipherOutputStream` from an `OutputStream` and a `Cipher` object.
protected	CipherOutputStream(OutputStream the `OutputStream` object os) Constructs a `CipherOutputStream` from an `OutputStream` without specifying a `Cipher` object.

Method Summary

Modifier and Type	Method and Description
public void	close() Overrides java.io.FilterOutputStream.close. Implements java.io.Closeable.close. Closes this output stream and releases any system resources associated with this 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) If obuffer is null/zero-sized, do not allocate a new buffer.
public void	flush() Overrides java.io.FilterOutputStream.flush. Implements java.io.Flushable.flush. Flushes this output stream by forcing any buffered output bytes that have already been processed by the encapsulated `Cipher` object to be written out.
public void	write(int the `byte`. b) Overrides java.io.FilterOutputStream.write. Writes the specified byte to this output stream.
public void	write(byte[] the data. b) Overrides java.io.FilterOutputStream.write. Writes `b.length` bytes from the specified byte array to this output stream.
public void	write(byte[] the data. b, int the start offset in the data. off, int the number of bytes to write. len) Overrides java.io.FilterOutputStream.write. Writes `len` bytes from the specified byte array starting at offset `off` to this output stream.

Field Detail

cipher	back to summary
private final Cipher cipher

closed	back to summary
private boolean closed Hides java.io.FilterOutputStream.closed.

ibuffer	back to summary
private final byte[] ibuffer

obuffer	back to summary
private byte[] obuffer

output	back to summary
private final OutputStream output

Constructor Detail

CipherOutputStream back to summary

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

public CipherOutputStream(OutputStream os, Cipher c)

Constructs a CipherOutputStream from an OutputStream and a Cipher object.

Note

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

Parameters

os:OutputStream: the OutputStream object
c:Cipher: an initialized Cipher object

CipherOutputStream back to summary

CipherOutputStream	back to summary
protected CipherOutputStream(OutputStream os) Constructs a `CipherOutputStream` from an `OutputStream` without specifying a `Cipher` object. This has the effect of constructing a `CipherOutputStream` using a `NullCipher`. Note if the specified output stream is `null`, a `NullPointerException` may be thrown later when it is used. Parameters os:OutputStream the `OutputStream` object

protected CipherOutputStream(OutputStream os)

Constructs a CipherOutputStream from an OutputStream without specifying a Cipher object. This has the effect of constructing a CipherOutputStream using a NullCipher.

Note

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

Parameters

os:OutputStream: the OutputStream object

Method Detail

close back to summary

close	back to summary
public void close() throws IOException Overrides java.io.FilterOutputStream.close. Implements java.io.Closeable.close. Closes this output stream and releases any system resources associated with this stream. This method invokes the `doFinal` method of the encapsulated `Cipher` object, which causes any bytes buffered by the encapsulated `Cipher` object to be processed. The result is written out by calling the `flush` method of this output stream. This method resets the encapsulated `Cipher` object to its initial state and calls the `close` method of the underlying output stream. Annotations @Override Exceptions IOException: if an I/O error occurs.

public void close() throws IOException

Overrides java.io.FilterOutputStream.close.

Implements java.io.Closeable.close.

Closes this output stream and releases any system resources associated with this stream.

This method invokes the doFinal method of the encapsulated Cipher object, which causes any bytes buffered by the encapsulated Cipher object to be processed. The result is written out by calling the flush method of this output stream.

This method resets the encapsulated Cipher object to its initial state and calls the close method of the underlying output 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) 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) 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)

flush back to summary

flush	back to summary
public void flush() throws IOException Overrides java.io.FilterOutputStream.flush. Implements java.io.Flushable.flush. Flushes this output stream by forcing any buffered output bytes that have already been processed by the encapsulated `Cipher` object to be written out. Any bytes buffered by the encapsulated `Cipher` object and waiting to be processed by it will not be written out. For example, if the encapsulated `Cipher` object is a block cipher, and the total number of bytes written using one of the `write` methods is less than the cipher's block size, no bytes will be written out. Annotations @Override Exceptions IOException: if an I/O error occurs.

public void flush() throws IOException

Overrides java.io.FilterOutputStream.flush.

Implements java.io.Flushable.flush.

Flushes this output stream by forcing any buffered output bytes that have already been processed by the encapsulated Cipher object to be written out.

Any bytes buffered by the encapsulated Cipher object and waiting to be processed by it will not be written out. For example, if the encapsulated Cipher object is a block cipher, and the total number of bytes written using one of the write methods is less than the cipher's block size, no bytes will be written out.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

write back to summary

write	back to summary
public void write(int b) throws IOException Overrides java.io.FilterOutputStream.write. Writes the specified byte to this output stream. Parameters b:int the `byte`. Annotations @Override Exceptions IOException: if an I/O error occurs.

public void write(int b) throws IOException

Overrides java.io.FilterOutputStream.write.

Writes the specified byte to this output stream.

Parameters

b:int: the byte.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

write back to summary

write	back to summary
public void write(byte[] b) throws IOException Overrides java.io.FilterOutputStream.write. Writes `b.length` bytes from the specified byte array to this output stream. The `write` method of `CipherOutputStream` calls the `write` method of three arguments with the three arguments `b`, `0`, and `b.length`. Parameters b:byte[] the data. Annotations @Override Exceptions IOException: if an I/O error occurs. NullPointerException: if `b` is `null`. See Also `javax.crypto.CipherOutputStream#write(byte[], int, int)`

public void write(byte[] b) throws IOException

Overrides java.io.FilterOutputStream.write.

Writes b.length bytes from the specified byte array to this output stream.

The write method of CipherOutputStream calls the write method of three arguments with the three arguments b, 0, and b.length.

Parameters

b:byte[]: the data.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.
NullPointerException:: if b is null.

write back to summary

write	back to summary
public void write(byte[] b, int off, int len) throws IOException Overrides java.io.FilterOutputStream.write. Writes `len` bytes from the specified byte array starting at offset `off` to this output stream. Parameters b:byte[] the data. off:int the start offset in the data. len:int the number of bytes to write. Annotations @Override Exceptions IOException: if an I/O error occurs.

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

Overrides java.io.FilterOutputStream.write.

Writes len bytes from the specified byte array starting at offset off to this output stream.

Parameters

b:byte[]: the data.
off:int: the start offset in the data.
len:int: the number of bytes to write.

Annotations

@Override

Exceptions

IOException:: if an I/O error occurs.

public Class CipherOutputStream

Field Summary

Constructor Summary

Method Summary

Field Detail

Constructor Detail

Method Detail