PGPEncryptedDataGenerator
Date: 2016-06-23

org.bouncycastle.openpgp

## Class PGPEncryptedDataGenerator

- java.lang.Object
- - org.bouncycastle.openpgp.PGPEncryptedDataGenerator

- All Implemented Interfaces:
    SymmetricKeyAlgorithmTags

      public class PGPEncryptedDataGenerator
      extends java.lang.Object
      implements SymmetricKeyAlgorithmTags

  Generator for encrypted objects.

  A PGPEncryptedDataGenerator is used by configuring one or more `encryption methods`, and then invoking one of the open functions to create an OutputStream that raw data can be supplied to for encryption:

  - If the length of the data to be written is known in advance, use `open(OutputStream, long)` to create a packet containing a single encrypted object.
  - If the length of the data is unknown, use `open(OutputStream, byte[])` to create an packet consisting of a series of encrypted objects (partials).

  Raw data is not typically written directly to the OutputStream obtained from a PGPEncryptedDataGenerator. The OutputStream is usually wrapped by a `PGPLiteralDataGenerator`, and often with a `PGPCompressedDataGenerator` between.

  Once plaintext data for encryption has been written to the constructed OutputStream, writing of the encrypted object stream is completed by closing the OutputStream obtained from the `open()` method, or equivalently invoking `close()` on this generator.

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `S2K_SHA1` Specifier for SHA-1 S2K PBE generator.
    `static int` | `S2K_SHA224` Specifier for SHA-224 S2K PBE generator.
    `static int` | `S2K_SHA256` Specifier for SHA-256 S2K PBE generator.
    `static int` | `S2K_SHA384` Specifier for SHA-384 S2K PBE generator.
    `static int` | `S2K_SHA512` Specifier for SHA-512 S2K PBE generator.

    - ### Fields inherited from interface org.bouncycastle.bcpg.SymmetricKeyAlgorithmTags

      `AES_128, AES_192, AES_256, BLOWFISH, CAMELLIA_128, CAMELLIA_192, CAMELLIA_256, CAST5, DES, IDEA, NULL, SAFER, TRIPLE_DES, TWOFISH`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PGPEncryptedDataGenerator(PGPDataEncryptorBuilder encryptorBuilder)` Base constructor.
    `PGPEncryptedDataGenerator(PGPDataEncryptorBuilder encryptorBuilder, boolean oldFormat)` Base constructor with the option to turn on formatting for PGP 2.6.x compatibility.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addMethod(PGPKeyEncryptionMethodGenerator method)` Add a key encryption method to be used to encrypt the session data associated with this encrypted data.
    `void` | `close()` Close off the encrypted object - this is equivalent to calling close on the stream returned by the `open()` methods.
    `java.io.OutputStream` | `open(java.io.OutputStream out, byte[] buffer)` Create an OutputStream which will encrypt the data as it is written to it.
    `java.io.OutputStream` | `open(java.io.OutputStream out, long length)` Create an OutputStream based on the configured methods to write a single encrypted object of known length.

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

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

- - ### Field Detail

    - #### S2K_SHA1

          public static final int S2K_SHA1

      Specifier for SHA-1 S2K PBE generator.
      See Also:
        Constant Field Values

    - #### S2K_SHA224

          public static final int S2K_SHA224

      Specifier for SHA-224 S2K PBE generator.
      See Also:
        Constant Field Values

    - #### S2K_SHA256

          public static final int S2K_SHA256

      Specifier for SHA-256 S2K PBE generator.
      See Also:
        Constant Field Values

    - #### S2K_SHA384

          public static final int S2K_SHA384

      Specifier for SHA-384 S2K PBE generator.
      See Also:
        Constant Field Values

    - #### S2K_SHA512

          public static final int S2K_SHA512

      Specifier for SHA-512 S2K PBE generator.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### PGPEncryptedDataGenerator

          public PGPEncryptedDataGenerator(PGPDataEncryptorBuilder encryptorBuilder)

      Base constructor.
      Parameters:
        `encryptorBuilder` - builder to create actual data encryptor.

    - #### PGPEncryptedDataGenerator

          public PGPEncryptedDataGenerator(PGPDataEncryptorBuilder encryptorBuilder,
                                   boolean oldFormat)

      Base constructor with the option to turn on formatting for PGP 2.6.x compatibility.
      Parameters:
        `encryptorBuilder` - builder to create actual data encryptor.
        `oldFormat` - PGP 2.6.x compatibility required.

  - ### Method Detail

    - #### addMethod

          public void addMethod(PGPKeyEncryptionMethodGenerator method)

      Add a key encryption method to be used to encrypt the session data associated with this encrypted data.
      Parameters:
        `method` - key encryption method to use.

    - #### open

          public java.io.OutputStream open(java.io.OutputStream out,
                                  long length)
                                    throws java.io.IOException,
                                           PGPException

      Create an OutputStream based on the configured methods to write a single encrypted object of known length.

      The stream created can be closed off by either calling close() on the stream or close() on the generator. Closing the returned stream does not close off the OutputStream parameter out.

      Parameters:
        `out` - the stream to write encrypted packets to.
        `length` - the length of the data to be encrypted.
      Returns:
        the output stream to write data to for encryption.
      Throws:
        `java.io.IOException` - if an error occurs writing stream header information to the provider output stream.
        `PGPException` - if an error occurs initialising PGP encryption for the configured encryption methods.
        `java.lang.IllegalStateException` - if this generator already has an open OutputStream, or no `encryption methods` are configured.

    - #### open

          public java.io.OutputStream open(java.io.OutputStream out,
                                  byte[] buffer)
                                    throws java.io.IOException,
                                           PGPException

      Create an OutputStream which will encrypt the data as it is written to it. The stream of encrypted data will be written out in chunks (partial packets) according to the size of the passed in buffer.

      The stream created can be closed off by either calling close() on the stream or close() on the generator. Closing the returned stream does not close off the OutputStream parameter out.

      Note: if the buffer is not a power of 2 in length only the largest power of 2 bytes worth of the buffer will be used.

      Parameters:
        `out` - the stream to write encrypted packets to.
        `buffer` - a buffer to use to buffer and write partial packets. The returned stream takes ownership of the buffer and will use it to buffer plaintext data for encryption.
      Returns:
        the output stream to write data to for encryption.
      Throws:
        `java.io.IOException` - if an error occurs writing stream header information to the provider output stream.
        `PGPException` - if an error occurs initialising PGP encryption for the configured encryption methods.
        `java.lang.IllegalStateException` - if this generator already has an open OutputStream, or no `encryption methods` are configured.

    - #### close

          public void close()
                     throws java.io.IOException

      Close off the encrypted object - this is equivalent to calling close on the stream returned by the `open()` methods.

      Note: This does not close the underlying output stream, only the stream on top of it created by the `open()` method.

      Throws:
        `java.io.IOException` - if an error occurs writing trailing information (such as integrity check information) to the underlying stream.