X0017_StrongEncryptionHeader
Date: 2017-02-08

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

- - ### Nested Class Summary

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

      `PKWareExtraHeader.EncryptionAlgorithm, PKWareExtraHeader.HashAlgorithm`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `X0017_StrongEncryptionHeader()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `PKWareExtraHeader.EncryptionAlgorithm` | `getEncryptionAlgorithm()` Get encryption algorithm.
    `PKWareExtraHeader.HashAlgorithm` | `getHashAlgorithm()` Get hash algorithm.
    `long` | `getRecordCount()` Get 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

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

    - #### X0017_StrongEncryptionHeader

          public X0017_StrongEncryptionHeader()

  - ### Method Detail

    - #### getRecordCount

          public long getRecordCount()

      Get record count.
      Returns:
        the record count

    - #### getHashAlgorithm

          public PKWareExtraHeader.HashAlgorithm getHashAlgorithm()

      Get hash algorithm.
      Returns:
        the hash algorithm

    - #### getEncryptionAlgorithm

          public PKWareExtraHeader.EncryptionAlgorithm getEncryptionAlgorithm()

      Get encryption algorithm.
      Returns:
        the encryption algorithm

    - #### parseCentralDirectoryFormat

          public void parseCentralDirectoryFormat(byte[] data,
                                         int offset,
                                         int length)

      Parse central directory format.
      Parameters:
        `data` - the buffer to read data from
        `offset` - offset into buffer to read data
        `length` - the length of data

    - #### parseFileFormat

          public void parseFileFormat(byte[] data,
                             int offset,
                             int length)

      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

    - #### parseFromLocalFileData

          public void parseFromLocalFileData(byte[] data,
                                    int offset,
                                    int length)

      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.
      See Also:
        `ZipExtraField.parseFromLocalFileData(byte[], int, int)`

    - #### parseFromCentralDirectoryData

          public void parseFromCentralDirectoryData(byte[] data,
                                           int offset,
                                           int length)

      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.
      See Also:
        `ZipExtraField.parseFromCentralDirectoryData(byte[], int, int)`