org.apache.poi.poifs.crypt

## Class EncryptionInfo

- java.lang.Object
- - org.apache.poi.poifs.crypt.EncryptionInfo

- All Implemented Interfaces:
    GenericRecord

      public class EncryptionInfo
      extends java.lang.Object
      implements GenericRecord

  This class may require `poi-ooxml` to be on the classpath to load some `EncryptionMode`s.
  See Also:
    `getBuilder(EncryptionMode)`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static BitField` | `flagAES` A value that MUST be 1 if the protected content is an ECMA-376 document ECMA-376.
    `static BitField` | `flagCryptoAPI` A flag that specifies whether CryptoAPI RC4 or ECMA-376 encryption ECMA-376 is used.
    `static BitField` | `flagDocProps` A value that MUST be 0 if document properties are encrypted.
    `static BitField` | `flagExternal` A value that MUST be 1 if extensible encryption is used.

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `EncryptionInfo(DirectoryNode dir)` Opens for decryption
    `EncryptionInfo(EncryptionInfo other)`
    `EncryptionInfo(EncryptionMode encryptionMode)` Prepares for encryption, using the given Encryption Mode, and all other parameters as default.
    `EncryptionInfo(EncryptionMode encryptionMode, CipherAlgorithm cipherAlgorithm, HashAlgorithm hashAlgorithm, int keyBits, int blockSize, ChainingMode chainingMode)` Constructs an EncryptionInfo from scratch
    `EncryptionInfo(LittleEndianInput dis, EncryptionMode preferredEncryptionMode)`
    `EncryptionInfo(POIFSFileSystem fs)` Opens for decryption

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `EncryptionInfo` | `copy()`
    `protected static EncryptionInfoBuilder` | `getBuilder(EncryptionMode encryptionMode)` This method loads the builder class with reflection, which may generate a `ClassNotFoundException` if the class is not on the classpath.
    `Decryptor` | `getDecryptor()`
    `int` | `getEncryptionFlags()`
    `EncryptionMode` | `getEncryptionMode()`
    `Encryptor` | `getEncryptor()`
    `java.util.Map<java.lang.String,java.util.function.Supplier<?>>` | `getGenericProperties()`
    `EncryptionHeader` | `getHeader()`
    `EncryptionVerifier` | `getVerifier()`
    `int` | `getVersionMajor()`
    `int` | `getVersionMinor()`
    `boolean` | `isDocPropsEncrypted()`
    `void` | `setDecryptor(Decryptor decryptor)`
    `void` | `setEncryptor(Encryptor encryptor)`
    `void` | `setHeader(EncryptionHeader header)`
    `void` | `setVerifier(EncryptionVerifier verifier)`

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

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

    - ### Methods inherited from interface org.apache.poi.common.usermodel.GenericRecord

      `getGenericChildren, getGenericRecordType`

- - ### Field Detail

    - #### flagCryptoAPI

          public static final BitField flagCryptoAPI

      A flag that specifies whether CryptoAPI RC4 or ECMA-376 encryption ECMA-376 is used. It MUST be 1 unless flagExternal is 1. If flagExternal is 1, it MUST be 0.

    - #### flagDocProps

          public static final BitField flagDocProps

      A value that MUST be 0 if document properties are encrypted. The encryption of document properties is specified in section 2.3.5.4.

    - #### flagExternal

          public static final BitField flagExternal

      A value that MUST be 1 if extensible encryption is used. If this value is 1, the value of every other field in this structure MUST be 0.

    - #### flagAES

          public static final BitField flagAES

      A value that MUST be 1 if the protected content is an ECMA-376 document ECMA-376. If the fAES bit is 1, the fCryptoAPI bit MUST also be 1.

  - ### Constructor Detail

    - #### EncryptionInfo

          public EncryptionInfo(POIFSFileSystem fs)
                         throws java.io.IOException

      Opens for decryption
      Throws:
        `java.io.IOException`

    - #### EncryptionInfo

          public EncryptionInfo(DirectoryNode dir)
                         throws java.io.IOException

      Opens for decryption
      Throws:
        `java.io.IOException`

    - #### EncryptionInfo

          public EncryptionInfo(LittleEndianInput dis,
                                EncryptionMode preferredEncryptionMode)
                         throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### EncryptionInfo

          public EncryptionInfo(EncryptionMode encryptionMode)

      Prepares for encryption, using the given Encryption Mode, and all other parameters as default.
      See Also:
        `EncryptionInfo(EncryptionMode, CipherAlgorithm, HashAlgorithm, int, int, ChainingMode)`

    - #### EncryptionInfo

          public EncryptionInfo(EncryptionMode encryptionMode,
                                CipherAlgorithm cipherAlgorithm,
                                HashAlgorithm hashAlgorithm,
                                int keyBits,
                                int blockSize,
                                ChainingMode chainingMode)

      Constructs an EncryptionInfo from scratch
      Parameters:
        `encryptionMode` - see `EncryptionMode` for values, `EncryptionMode.cryptoAPI` is for internal use only, as it's record based
        `cipherAlgorithm` - the cipher algorithm
        `hashAlgorithm` - the hash algorithm
        `keyBits` - the bit count of the key
        `blockSize` - the size of a cipher block
        `chainingMode` - the chaining mode
      Throws:
        `EncryptedDocumentException` - if the given parameters mismatch, e.g. only certain combinations of keyBits, blockSize are allowed for a given `CipherAlgorithm`

    - #### EncryptionInfo

          public EncryptionInfo(EncryptionInfo other)

  - ### Method Detail

    - #### getBuilder

          protected static EncryptionInfoBuilder getBuilder(EncryptionMode encryptionMode)
                                                     throws java.lang.ClassNotFoundException,
                                                            java.lang.IllegalAccessException,
                                                            java.lang.InstantiationException

      This method loads the builder class with reflection, which may generate a `ClassNotFoundException` if the class is not on the classpath. For example, `AgileEncryptionInfoBuilder` is contained in the `poi-ooxml` package since the class makes use of some OOXML classes rather than using the `poi` package and plain XML DOM calls. As such, you may need to include `poi-ooxml` and `poi-ooxml-schemas` to load some encryption mode builders. See bug #60021 for more information. https://bz.apache.org/bugzilla/show_bug.cgi?id=60021
      Parameters:
        `encryptionMode` - the encryption mode
      Returns:
        an encryption info builder
      Throws:
        `java.lang.ClassNotFoundException` - if the builder class is not on the classpath
        `java.lang.IllegalAccessException` - if the builder class can't be loaded
        `java.lang.InstantiationException` - if the builder class can't be loaded

    - #### getVersionMajor

          public int getVersionMajor()

    - #### getVersionMinor

          public int getVersionMinor()

    - #### getEncryptionFlags

          public int getEncryptionFlags()

    - #### getHeader

          public EncryptionHeader getHeader()

    - #### getVerifier

          public EncryptionVerifier getVerifier()

    - #### getDecryptor

          public Decryptor getDecryptor()

    - #### getEncryptor

          public Encryptor getEncryptor()

    - #### setHeader

          public void setHeader(EncryptionHeader header)

    - #### setVerifier

          public void setVerifier(EncryptionVerifier verifier)

    - #### setDecryptor

          public void setDecryptor(Decryptor decryptor)

    - #### setEncryptor

          public void setEncryptor(Encryptor encryptor)

    - #### getEncryptionMode

          public EncryptionMode getEncryptionMode()

    - #### isDocPropsEncrypted

          public boolean isDocPropsEncrypted()

      Returns:
        true, if Document Summary / Summary are encrypted and stored in the `EncryptedStream` stream, otherwise the Summaries aren't encrypted and located in their usual streams

    - #### copy

          public EncryptionInfo copy()

    - #### getGenericProperties

          public java.util.Map<java.lang.String,java.util.function.Supplier<?>> getGenericProperties()

      Specified by:
        `getGenericProperties` in interface `GenericRecord`

Copyright 2020 The Apache Software Foundation or its licensors, as applicable.