:py:mod:`dissect.hypervisor.util.envelope`
==========================================

.. py:module:: dissect.hypervisor.util.envelope




Module Contents
---------------

Classes
~~~~~~~

.. autoapisummary::

   dissect.hypervisor.util.envelope.EnvelopeAttribute
   dissect.hypervisor.util.envelope.Envelope
   dissect.hypervisor.util.envelope.KeyStore




Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.hypervisor.util.envelope.HAS_PYSTANDALONE
   dissect.hypervisor.util.envelope.HAS_PYCRYPTODOME
   dissect.hypervisor.util.envelope.c_def
   dissect.hypervisor.util.envelope.c_envelope
   dissect.hypervisor.util.envelope.FILE_HEADER_MAGIC
   dissect.hypervisor.util.envelope.FOOTER_AEAD_MAGIC
   dissect.hypervisor.util.envelope.FOOTER_CRYPTO_MAGIC
   dissect.hypervisor.util.envelope.PBKDF2_SALT
   dissect.hypervisor.util.envelope.ENVELOPE_BLOCK_SIZE
   dissect.hypervisor.util.envelope.ENVELOPE_ATTRIBUTE_TYPE_MAP
   dissect.hypervisor.util.envelope.DECRYPT_CHUNK_SIZE


.. py:data:: HAS_PYSTANDALONE
   :value: True


.. py:data:: HAS_PYCRYPTODOME
   :value: True


.. py:data:: c_def
   :value: Multiline-String

   .. raw:: html

      <details><summary>Show Value</summary>

   .. code-block:: python

      """
      struct EnvelopeFileHeader {
          char    magic[21];
          char    _pad[483];
          uint32  size;
          uint32  version;
      };
      
      struct DataTransformAeadFooter {
          char    magic[23];
          char    _pad[9];
          char    data[4056];
          uint32  size;
          uint32  version;
      };
      
      struct DataTransformCryptoFooter {
          char    magic[25];
          char    _pad[479];
          uint32  padding;
          uint32  version;
      };
      
      enum AttributeType : uint8 {
          Invalid = 0x0,
          // These are guesses based on size and used attributes
          UInt8 = 0x1,
          UInt16 = 0x2,
          UInt32 = 0x3,
          UInt64 = 0x4,
          Int8 = 0x5,
          Int16 = 0x6,
          Int32 = 0x7,
          Int64 = 0x8,
          Float = 0x9,
          Double = 0xA,
          // These are certain
          String = 0xB,
          Bytes = 0xC
      };
      """

   .. raw:: html

      </details>



.. py:data:: c_envelope

.. py:data:: FILE_HEADER_MAGIC
   :value: b'DataTransformEnvelope'


.. py:data:: FOOTER_AEAD_MAGIC
   :value: b'DataTransformAeadFooter'


.. py:data:: FOOTER_CRYPTO_MAGIC
   :value: b'DataTransformCryptoFooter'


.. py:data:: PBKDF2_SALT
   :value: b'This is obfuscation, not encryption. If you want encryption, use TPM.'


.. py:data:: ENVELOPE_BLOCK_SIZE
   :value: 4096


.. py:data:: ENVELOPE_ATTRIBUTE_TYPE_MAP

.. py:data:: DECRYPT_CHUNK_SIZE
   :value: 4194304


.. py:class:: EnvelopeAttribute

   Bases: :py:obj:`NamedTuple`


   .. py:attribute:: type
      :type:  int


   .. py:attribute:: flag
      :type:  int


   .. py:attribute:: value
      :type:  bytes


.. py:class:: Envelope(fh: BinaryIO, verify: bool = True)

   Implements an encryption envelope as used within ESXi.


   .. py:attribute:: fh


   .. py:attribute:: verify
      :value: True



   .. py:attribute:: header


   .. py:attribute:: version


   .. py:attribute:: attributes


   .. py:attribute:: key_info


   .. py:attribute:: cipher_name


   .. py:attribute:: key_hash


   .. py:attribute:: iv


   .. py:attribute:: digest
      :value: None



   .. py:attribute:: size


   .. py:attribute:: data


   .. py:method:: decrypt(key: bytes, aad: bytes | None = None) -> bytes

      Decrypt the data in this envelope.

      :param key: decryption key to use
      :param aad: optional associated data to include for AEAD ciphers



.. py:class:: KeyStore(store: dict[str, str])

   Implements a file based keystore as used in ESXi.


   .. py:attribute:: store


   .. py:attribute:: mode


   .. py:property:: id
      :type: str



   .. py:property:: key
      :type: bytes



   .. py:method:: from_text(text: str) -> KeyStore
      :classmethod:


      Parse a key store from a string.

      :param text: string to parse a key store from