CryptoOutputStream (Apache Hadoop Common 3.5.0 API)
Description: declaration: package: org.apache.hadoop.crypto, class: CryptoOutputStream

Package org.apache.hadoop.crypto

# Class CryptoOutputStream

java.lang.Object
java.io.OutputStream
java.io.FilterOutputStream
org.apache.hadoop.crypto.CryptoOutputStream

All Implemented Interfaces:
  `Closeable`, `Flushable`, `AutoCloseable`, `CanSetDropBehind`, `IOStatisticsSource`, `StreamCapabilities`, `Syncable`

@Private @Evolving public class CryptoOutputStream extends FilterOutputStream implements Syncable, CanSetDropBehind, StreamCapabilities, IOStatisticsSource
CryptoOutputStream encrypts data. It is not thread-safe. AES CTR mode is required in order to ensure that the plain text and cipher text have a 1:1 mapping. The encryption is buffer based. The key points of the encryption are (1) calculating counter and (2) padding through stream position.

counter = base + pos/(algorithm blocksize); padding = pos%(algorithm blocksize);

The underlying stream offset is maintained as state. Note that while some of this class' methods are synchronized, this is just to match the threadsafety behavior of DFSOutputStream. See HADOOP-11710.

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from interface org.apache.hadoop.fs.StreamCapabilities

  `StreamCapabilities.StreamCapability`

- ## Field Summary

  ### Fields inherited from class java.io.FilterOutputStream

  `out`

  ### Fields inherited from interface org.apache.hadoop.fs.StreamCapabilities

  `ABORTABLE_STREAM, DROPBEHIND, HFLUSH, HSYNC, IOSTATISTICS, IOSTATISTICS_CONTEXT, PREADBYTEBUFFER, READAHEAD, READBYTEBUFFER, UNBUFFER, VECTOREDIO, VECTOREDIO_BUFFERS_SLICED`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CryptoOutputStream(OutputStream out, CryptoCodec codec, byte[] key, byte[] iv)`
  `CryptoOutputStream(OutputStream out, CryptoCodec codec, byte[] key, byte[] iv, long streamOffset)`
  `CryptoOutputStream(OutputStream out, CryptoCodec codec, byte[] key, byte[] iv, long streamOffset, boolean closeOutputStream)`
  `CryptoOutputStream(OutputStream out, CryptoCodec codec, int bufferSize, byte[] key, byte[] iv)`
  `CryptoOutputStream(OutputStream out, CryptoCodec codec, int bufferSize, byte[] key, byte[] iv, long streamOffset)`
  `CryptoOutputStream(OutputStream out, CryptoCodec codec, int bufferSize, byte[] key, byte[] iv, long streamOffset, boolean closeOutputStream)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `close()`
  `void`
  `flush()`
  To flush, we need to encrypt the data in the buffer and write to the underlying stream, then do the flush.
  `IOStatistics`
  `getIOStatistics()`
  Return a statistics instance.
  `OutputStream`
  `getWrappedStream()`
  `boolean`
  `hasCapability(String capability)`
  Query the stream for a specific capability.
  `void`
  `hflush()`
  Flush out the data in client's user buffer.
  `void`
  `hsync()`
  Similar to posix fsync, flush out the data in client's user buffer all the way to the disk device (but the disk may have it in its cache).
  `void`
  `setDropBehind(Boolean dropCache)`
  Configure whether the stream should drop the cache.
  `void`
  `write(byte[] b, int off, int len)`
  Encryption is buffer based.
  `void`
  `write(int b)`

  ### Methods inherited from class java.io.FilterOutputStream

  `write`

  ### Methods inherited from class java.io.OutputStream

  `nullOutputStream`

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

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

- ## Constructor Details

  - ### CryptoOutputStream

    public CryptoOutputStream(OutputStream out, CryptoCodec codec, int bufferSize, byte[] key, byte[] iv) throws IOException
    Throws:
      `IOException`

  - ### CryptoOutputStream

    public CryptoOutputStream(OutputStream out, CryptoCodec codec, int bufferSize, byte[] key, byte[] iv, long streamOffset) throws IOException
    Throws:
      `IOException`

  - ### CryptoOutputStream

    public CryptoOutputStream(OutputStream out, CryptoCodec codec, int bufferSize, byte[] key, byte[] iv, long streamOffset, boolean closeOutputStream) throws IOException
    Throws:
      `IOException`

  - ### CryptoOutputStream

    public CryptoOutputStream(OutputStream out, CryptoCodec codec, byte[] key, byte[] iv) throws IOException
    Throws:
      `IOException`

  - ### CryptoOutputStream

    public CryptoOutputStream(OutputStream out, CryptoCodec codec, byte[] key, byte[] iv, long streamOffset) throws IOException
    Throws:
      `IOException`

  - ### CryptoOutputStream

    public CryptoOutputStream(OutputStream out, CryptoCodec codec, byte[] key, byte[] iv, long streamOffset, boolean closeOutputStream) throws IOException
    Throws:
      `IOException`

- ## Method Details

  - ### getWrappedStream

    public OutputStream getWrappedStream()

  - ### write

    public void write(byte[] b, int off, int len) throws IOException
    Encryption is buffer based. If there is enough room in `inBuffer`, then write to this buffer. If `inBuffer` is full, then do encryption and write data to the underlying stream.
    Overrides:
      `write` in class `FilterOutputStream`
    Parameters:
      `b` - the data.
      `off` - the start offset in the data.
      `len` - the number of bytes to write.
    Throws:
      `IOException` - raised on errors performing I/O.

  - ### close

    public void close() throws IOException
    Specified by:
      `close` in interface `AutoCloseable`
    Specified by:
      `close` in interface `Closeable`
    Overrides:
      `close` in class `FilterOutputStream`
    Throws:
      `IOException`

  - ### flush

    public void flush() throws IOException
    To flush, we need to encrypt the data in the buffer and write to the underlying stream, then do the flush.
    Specified by:
      `flush` in interface `Flushable`
    Overrides:
      `flush` in class `FilterOutputStream`
    Throws:
      `IOException`

  - ### write

    public void write(int b) throws IOException
    Overrides:
      `write` in class `FilterOutputStream`
    Throws:
      `IOException`

  - ### setDropBehind

    public void setDropBehind(Boolean dropCache) throws IOException, UnsupportedOperationException
    Description copied from interface: `CanSetDropBehind`
    Configure whether the stream should drop the cache.
    Specified by:
      `setDropBehind` in interface `CanSetDropBehind`
    Parameters:
      `dropCache` - Whether to drop the cache. null means to use the default value.
    Throws:
      `IOException` - If there was an error changing the dropBehind setting. UnsupportedOperationException If this stream doesn't support setting the drop-behind.
      `UnsupportedOperationException`

  - ### hflush

    public void hflush() throws IOException
    Description copied from interface: `Syncable`
    Flush out the data in client's user buffer. After the return of this call, new readers will see the data.
    Specified by:
      `hflush` in interface `Syncable`
    Throws:
      `IOException` - if any error occurs

  - ### hsync

    public void hsync() throws IOException
    Description copied from interface: `Syncable`
    Similar to posix fsync, flush out the data in client's user buffer all the way to the disk device (but the disk may have it in its cache).
    Specified by:
      `hsync` in interface `Syncable`
    Throws:
      `IOException` - if error occurs

  - ### hasCapability

    public boolean hasCapability(String capability)
    Description copied from interface: `StreamCapabilities`
    Query the stream for a specific capability.
    Specified by:
      `hasCapability` in interface `StreamCapabilities`
    Parameters:
      `capability` - string to query the stream support for.
    Returns:
      True if the stream supports capability.

  - ### getIOStatistics

    public IOStatistics getIOStatistics()
    Description copied from interface: `IOStatisticsSource`
    Return a statistics instance.

    It is not a requirement that the same instance is returned every time. `IOStatisticsSource`.

    If the object implementing this is Closeable, this method may return null if invoked on a closed object, even if it returns a valid instance when called earlier.

    Specified by:
      `getIOStatistics` in interface `IOStatisticsSource`
    Returns:
      an IOStatistics instance or null