org.apache.poi.poifs.crypt.cryptoapi

## Class CryptoAPIDecryptor

- java.lang.Object
- - org.apache.poi.poifs.crypt.Decryptor
  - - org.apache.poi.poifs.crypt.cryptoapi.CryptoAPIDecryptor

- All Implemented Interfaces:
    GenericRecord

      public class CryptoAPIDecryptor
      extends Decryptor

- - ### Field Summary

    - ### Fields inherited from class org.apache.poi.poifs.crypt.Decryptor

      `DEFAULT_PASSWORD, DEFAULT_POIFS_ENTRY, encryptionInfo`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `CryptoAPIDecryptor()`
    `protected` | `CryptoAPIDecryptor(CryptoAPIDecryptor other)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `CryptoAPIDecryptor` | `copy()`
    `protected static javax.crypto.SecretKey` | `generateSecretKey(java.lang.String password, EncryptionVerifier ver)`
    `ChunkedCipherInputStream` | `getDataStream(DirectoryNode dir)` Return a stream with decrypted data.
    `ChunkedCipherInputStream` | `getDataStream(java.io.InputStream stream, int size, int initialPos)` Wraps a stream for decryption
    `long` | `getLength()` Returns the length of the encrypted data that can be safely read with `Decryptor.getDataStream(org.apache.poi.poifs.filesystem.DirectoryNode)`.
    `POIFSFileSystem` | `getSummaryEntries(DirectoryNode root, java.lang.String encryptedStream)` Decrypt the Document-/SummaryInformation and other optionally streams.
    `javax.crypto.Cipher` | `initCipherForBlock(javax.crypto.Cipher cipher, int block)` Initializes a cipher object for a given block index for encryption
    `protected static javax.crypto.Cipher` | `initCipherForBlock(javax.crypto.Cipher cipher, int block, EncryptionInfo encryptionInfo, javax.crypto.SecretKey skey, int encryptMode)`
    `void` | `setChunkSize(int chunkSize)` Sets the chunk size of the data stream.
    `boolean` | `verifyPassword(java.lang.String password)`

    - ### Methods inherited from class org.apache.poi.poifs.crypt.Decryptor

      `getBlockSizeInBytes, getDataStream, getEncryptionInfo, getGenericProperties, getInstance, getIntegrityHmacKey, getIntegrityHmacValue, getKeySizeInBytes, getSecretKey, getVerifier, setEncryptionInfo, setIntegrityHmacKey, setIntegrityHmacValue, setSecretKey, setVerifier`

    - ### 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`

- - ### Constructor Detail

    - #### CryptoAPIDecryptor

          protected CryptoAPIDecryptor()

    - #### CryptoAPIDecryptor

          protected CryptoAPIDecryptor(CryptoAPIDecryptor other)

  - ### Method Detail

    - #### verifyPassword

          public boolean verifyPassword(java.lang.String password)

      Specified by:
        `verifyPassword` in class `Decryptor`

    - #### initCipherForBlock

          public javax.crypto.Cipher initCipherForBlock(javax.crypto.Cipher cipher,
                                                        int block)
                                                 throws java.security.GeneralSecurityException

      Description copied from class: `Decryptor`
      Initializes a cipher object for a given block index for encryption
      Overrides:
        `initCipherForBlock` in class `Decryptor`
      Parameters:
        `cipher` - may be null, otherwise the given instance is reset to the new block index
        `block` - the block index, e.g. the persist/slide id (hslf)
      Returns:
        a new cipher object, if cipher was null, otherwise the reinitialized cipher
      Throws:
        `java.security.GeneralSecurityException` - if the cipher can't be initialized

    - #### initCipherForBlock

          protected static javax.crypto.Cipher initCipherForBlock(javax.crypto.Cipher cipher,
                                                                  int block,
                                                                  EncryptionInfo encryptionInfo,
                                                                  javax.crypto.SecretKey skey,
                                                                  int encryptMode)
                                                           throws java.security.GeneralSecurityException

      Throws:
        `java.security.GeneralSecurityException`

    - #### generateSecretKey

          protected static javax.crypto.SecretKey generateSecretKey(java.lang.String password,
                                                                    EncryptionVerifier ver)

    - #### getDataStream

          public ChunkedCipherInputStream getDataStream(DirectoryNode dir)
                                                 throws java.io.IOException,
                                                        java.security.GeneralSecurityException

      Description copied from class: `Decryptor`
      Return a stream with decrypted data.

      Use `Decryptor.getLength()` to get the size of that data that can be safely read from the stream. Just reading to the end of the input stream is not sufficient because there are normally padding bytes that must be discarded

      Specified by:
        `getDataStream` in class `Decryptor`
      Parameters:
        `dir` - the node to read from
      Returns:
        decrypted stream
      Throws:
        `java.io.IOException`
        `java.security.GeneralSecurityException`

    - #### getDataStream

          public ChunkedCipherInputStream getDataStream(java.io.InputStream stream,
                                                        int size,
                                                        int initialPos)
                                                 throws java.io.IOException,
                                                        java.security.GeneralSecurityException

      Description copied from class: `Decryptor`
      Wraps a stream for decryption

      As we are handling streams and don't know the total length beforehand, it's the callers duty to care for the length of the entries.

      Overrides:
        `getDataStream` in class `Decryptor`
      Parameters:
        `stream` - the stream to be wrapped
        `initialPos` - initial/current byte position within the stream
      Returns:
        decrypted stream
      Throws:
        `java.io.IOException`
        `java.security.GeneralSecurityException`

    - #### getSummaryEntries

          public POIFSFileSystem getSummaryEntries(DirectoryNode root,
                                                   java.lang.String encryptedStream)
                                            throws java.io.IOException,
                                                   java.security.GeneralSecurityException

      Decrypt the Document-/SummaryInformation and other optionally streams. Opposed to other crypto modes, cryptoapi is record based and can't be used to stream-decrypt a whole file.

      Summary entries are only encrypted within cryptoapi encrypted files. Binary RC4 encrypted files use non-encrypted/default property sets

      Parameters:
        `root` - root directory node of the OLE file containing the encrypted properties
        `encryptedStream` - name of the encrypted stream - "encryption" for HSSF/HWPF, "encryptedStream" (or encryptedSummary?) for HSLF
      Throws:
        `java.io.IOException`
        `java.security.GeneralSecurityException`
      See Also:
        2.3.5.4 RC4 CryptoAPI Encrypted Summary Stream

    - #### getLength

          public long getLength()

      Description copied from class: `Decryptor`
      Returns the length of the encrypted data that can be safely read with `Decryptor.getDataStream(org.apache.poi.poifs.filesystem.DirectoryNode)`. Just reading to the end of the input stream is not sufficient because there are normally padding bytes that must be discarded

      The length variable is initialized in `Decryptor.getDataStream(org.apache.poi.poifs.filesystem.DirectoryNode)`, an attempt to call getLength() prior to getDataStream() will result in IllegalStateException.

      Specified by:
        `getLength` in class `Decryptor`
      Returns:
        the length of the stream returned by `getDataStream(DirectoryNode)`

    - #### setChunkSize

          public void setChunkSize(int chunkSize)

      Description copied from class: `Decryptor`
      Sets the chunk size of the data stream. Needs to be set before the data stream is requested. When not set, the implementation uses method specific default values
      Overrides:
        `setChunkSize` in class `Decryptor`
      Parameters:
        `chunkSize` - the chunk size, i.e. the block size with the same encryption key

    - #### copy

          public CryptoAPIDecryptor copy()

      Specified by:
        `copy` in class `Decryptor`

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