Package org.apache.commons.compress.archivers.zip

# Class X0017_StrongEncryptionHeader

java.lang.Object
org.apache.commons.compress.archivers.zip.PKWareExtraHeader
org.apache.commons.compress.archivers.zip.X0017_StrongEncryptionHeader

All Implemented Interfaces:
  `ZipExtraField`

public class X0017_StrongEncryptionHeader extends PKWareExtraHeader
Strong Encryption Header (0x0017).

Certificate-based encryption:

     Value     Size     Description
     -----     ----     -----------
     0x0017    2 bytes  Tag for this "extra" block type
     TSize     2 bytes  Size of data that follows
     Format    2 bytes  Format definition for this record
     AlgID     2 bytes  Encryption algorithm identifier
     Bitlen    2 bytes  Bit length of encryption key (32-448 bits)
     Flags     2 bytes  Processing flags
     RCount    4 bytes  Number of recipients.
     HashAlg   2 bytes  Hash algorithm identifier
     HSize     2 bytes  Hash size
     SRList    (var)    Simple list of recipients hashed public keys

     Flags -   This defines the processing flags.

- 0x0007 - reserved for future use
- 0x000F - reserved for future use
- 0x0100 - Indicates non-OAEP key wrapping was used. If this this field is set, the version needed to extract must be at least 61. This means OAEP key wrapping is not used when generating a Master Session Key using ErdData.
- 0x4000 - ErdData must be decrypted using 3DES-168, otherwise use the same algorithm used for encrypting the file contents.
- 0x8000 - reserved for future use

     RCount - This defines the number intended recipients whose
              public keys were used for encryption.  This identifies
              the number of elements in the SRList.

              see also: reserved1

     HashAlg - This defines the hash algorithm used to calculate
               the public key hash of each public key used
               for encryption. This field currently supports
               only the following value for SHA-1

               0x8004 - SHA1

     HSize -   This defines the size of a hashed public key.

     SRList -  This is a variable length list of the hashed
               public keys for each intended recipient.  Each
               element in this list is HSize.  The total size of
               SRList is determined using RCount * HSize.

Password-based Extra Field 0x0017 in central header only.

     Value     Size     Description
     -----     ----     -----------
     0x0017    2 bytes  Tag for this "extra" block type
     TSize     2 bytes  Size of data that follows
     Format    2 bytes  Format definition for this record
     AlgID     2 bytes  Encryption algorithm identifier
     Bitlen    2 bytes  Bit length of encryption key (32-448 bits)
     Flags     2 bytes  Processing flags
     (more?)

Format - the data format identifier for this record. The only value allowed at this time is the integer value 2.

Password-based Extra Field 0x0017 preceding compressed file data.

     Value     Size     Description
     -----     ----     -----------
     0x0017    2 bytes  Tag for this "extra" block type
     IVSize    2 bytes  Size of initialization vector (IV)
     IVData    IVSize   Initialization vector for this file
     Size      4 bytes  Size of remaining decryption header data
     Format    2 bytes  Format definition for this record
     AlgID     2 bytes  Encryption algorithm identifier
     Bitlen    2 bytes  Bit length of encryption key (32-448 bits)
     Flags     2 bytes  Processing flags
     ErdSize   2 bytes  Size of Encrypted Random Data
     ErdData   ErdSize  Encrypted Random Data
     Reserved1 4 bytes  Reserved certificate processing data
     Reserved2 (var)    Reserved for certificate processing data
     VSize     2 bytes  Size of password validation data
     VData     VSize-4  Password validation data
     VCRC32    4 bytes  Standard ZIP CRC32 of password validation data

     IVData - The size of the IV should match the algorithm block size.
              The IVData can be completely random data.  If the size of
              the randomly generated data does not match the block size
              it should be complemented with zero's or truncated as
              necessary.  If IVSize is 0, then IV = CRC32 + Uncompressed
              File Size (as a 64 bit little-endian, unsigned integer value).

     Format -  the data format identifier for this record.  The only
               value allowed at this time is the integer value 2.

     ErdData - Encrypted random data is used to store random data that
               is used to generate a file session key for encrypting
               each file.  SHA1 is used to calculate hash data used to
               derive keys.  File session keys are derived from a master
               session key generated from the user-supplied password.
               If the Flags field in the decryption header contains
               the value 0x4000, then the ErdData field must be
               decrypted using 3DES. If the value 0x4000 is not set,
               then the ErdData field must be decrypted using AlgId.

     Reserved1 - Reserved for certificate processing, if value is
               zero, then Reserved2 data is absent.  See the explanation
               under the Certificate Processing Method for details on
               this data structure.

     Reserved2 - If present, the size of the Reserved2 data structure
               is located by skipping the first 4 bytes of this field
               and using the next 2 bytes as the remaining size.  See
               the explanation under the Certificate Processing Method
               for details on this data structure.

     VSize - This size value will always include the 4 bytes of the
             VCRC32 data and will be greater than 4 bytes.

     VData - Random data for password validation.  This data is VSize
             in length and VSize must be a multiple of the encryption
             block size.  VCRC32 is a checksum value of VData.
             VData and VCRC32 are stored encrypted and start the
             stream of encrypted data for a file.

Reserved1 - Certificate Decryption Header Reserved1 Data:

     Value     Size     Description
     -----     ----     -----------
     RCount    4 bytes  Number of recipients.

RCount - This defines the number intended recipients whose public keys were used for encryption. This defines the number of elements in the REList field defined below.

Reserved2 - Certificate Decryption Header Reserved2 Data Structures:

     Value     Size     Description
     -----     ----     -----------
     HashAlg   2 bytes  Hash algorithm identifier
     HSize     2 bytes  Hash size
     REList    (var)    List of recipient data elements

     HashAlg - This defines the hash algorithm used to calculate
               the public key hash of each public key used
               for encryption. This field currently supports
               only the following value for SHA-1

                   0x8004 - SHA1

     HSize -   This defines the size of a hashed public key
               defined in REHData.

     REList -  This is a variable length of list of recipient data.
               Each element in this list consists of a Recipient
               Element data structure as follows:

Recipient Element (REList) Data Structure:

     Value     Size     Description
     -----     ----     -----------
     RESize    2 bytes  Size of REHData + REKData
     REHData   HSize    Hash of recipients public key
     REKData   (var)    Simple key blob

     RESize -  This defines the size of an individual REList
               element.  This value is the combined size of the
               REHData field + REKData field.  REHData is defined by
               HSize.  REKData is variable and can be calculated
               for each REList element using RESize and HSize.

     REHData - Hashed public key for this recipient.

     REKData - Simple Key Blob.  The format of this data structure
               is identical to that defined in the Microsoft
               CryptoAPI and generated using the CryptExportKey()
               function.  The version of the Simple Key Blob
               supported at this time is 0x02 as defined by
               Microsoft.

               For more details see https://msdn.microsoft.com/en-us/library/aa920051.aspx

Flags - Processing flags needed for decryption

- 0x0001 - Password is required to decrypt
- 0x0002 - Certificates only
- 0x0003 - Password or certificate required to decrypt
- 0x0007 - reserved for future use
- 0x000F - reserved for future use
- 0x0100 - indicates non-OAEP key wrapping was used. If this field is set the version needed to extract must be at least 61. This means OAEP key wrapping is not used when generating a Master Session Key using ErdData.
- 0x4000 - ErdData must be decrypted using 3DES-168, otherwise use the same algorithm used for encrypting the file contents.
- 0x8000 - reserved for future use.

See the section describing the Strong Encryption Specification for details. Refer to the section in this document entitled "Incorporating PKWARE Proprietary Technology into Your Product" for more information.

Since:
  1.11
This class is not thread-safe

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class org.apache.commons.compress.archivers.zip.PKWareExtraHeader

  `PKWareExtraHeader.EncryptionAlgorithm, PKWareExtraHeader.HashAlgorithm`

- ## Field Summary

  ### Fields inherited from interface org.apache.commons.compress.archivers.zip.ZipExtraField

  `EXTRAFIELD_HEADER_SIZE`

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `X0017_StrongEncryptionHeader()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `PKWareExtraHeader.EncryptionAlgorithm`
  `getEncryptionAlgorithm()`
  Gets encryption algorithm.
  `PKWareExtraHeader.HashAlgorithm`
  `getHashAlgorithm()`
  Gets hash algorithm.
  `long`
  `getRecordCount()`
  Gets record count.
  `void`
  `parseCentralDirectoryFormat(byte[] data, int offset, int length)`
  Parse central directory format.
  `void`
  `parseFileFormat(byte[] data, int offset, int length)`
  Parse file header format.
  `void`
  `parseFromCentralDirectoryData(byte[] data, int offset, int length)`
  Populate data from this array as if it was in central directory data.
  `void`
  `parseFromLocalFileData(byte[] data, int offset, int length)`
  Populate data from this array as if it was in local file data.

  ### Methods inherited from class org.apache.commons.compress.archivers.zip.PKWareExtraHeader

  `assertMinimalLength, getCentralDirectoryData, getCentralDirectoryLength, getHeaderId, getLocalFileDataData, getLocalFileDataLength, setCentralDirectoryData, setLocalFileDataData`

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

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

- ## Constructor Details

  - ### X0017_StrongEncryptionHeader

    public X0017_StrongEncryptionHeader()

- ## Method Details

  - ### getEncryptionAlgorithm

    public PKWareExtraHeader.EncryptionAlgorithm getEncryptionAlgorithm()
    Gets encryption algorithm.
    Returns:
      the encryption algorithm

  - ### getHashAlgorithm

    public PKWareExtraHeader.HashAlgorithm getHashAlgorithm()
    Gets hash algorithm.
    Returns:
      the hash algorithm

  - ### getRecordCount

    public long getRecordCount()
    Gets record count.
    Returns:
      the record count

  - ### parseCentralDirectoryFormat

    public void parseCentralDirectoryFormat(byte[] data, int offset, int length) throws ZipException
    Parse central directory format.
    Parameters:
      `data` - the buffer to read data from
      `offset` - offset into buffer to read data
      `length` - the length of data
    Throws:
      `ZipException` - if an error occurs

  - ### parseFileFormat

    public void parseFileFormat(byte[] data, int offset, int length) throws ZipException
    Parse file header format.

    (Password only?)

    Parameters:
      `data` - the buffer to read data from
      `offset` - offset into buffer to read data
      `length` - the length of data
    Throws:
      `ZipException` - if an error occurs

  - ### parseFromCentralDirectoryData

    public void parseFromCentralDirectoryData(byte[] data, int offset, int length) throws ZipException
    Description copied from interface: `ZipExtraField`
    Populate data from this array as if it was in central directory data.
    Specified by:
      `parseFromCentralDirectoryData` in interface `ZipExtraField`
    Overrides:
      `parseFromCentralDirectoryData` in class `PKWareExtraHeader`
    Parameters:
      `data` - the array of bytes.
      `offset` - the source location in the data array.
      `length` - the number of bytes to use in the data array.
    Throws:
      `ZipException` - on error
    See Also:
      - `ZipExtraField.parseFromCentralDirectoryData(byte[], int, int)`

  - ### parseFromLocalFileData

    public void parseFromLocalFileData(byte[] data, int offset, int length) throws ZipException
    Description copied from interface: `ZipExtraField`
    Populate data from this array as if it was in local file data.
    Specified by:
      `parseFromLocalFileData` in interface `ZipExtraField`
    Overrides:
      `parseFromLocalFileData` in class `PKWareExtraHeader`
    Parameters:
      `data` - the array of bytes.
      `offset` - the source location in the data array.
      `length` - the number of bytes to use in the data array.
    Throws:
      `ZipException` - on error
    See Also:
      - `ZipExtraField.parseFromLocalFileData(byte[], int, int)`