:py:mod:`dissect.hypervisor.descriptor.vmx`
===========================================

.. py:module:: dissect.hypervisor.descriptor.vmx




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

Classes
~~~~~~~

.. autoapisummary::

   dissect.hypervisor.descriptor.vmx.VMX
   dissect.hypervisor.descriptor.vmx.KeySafe
   dissect.hypervisor.descriptor.vmx.Pair
   dissect.hypervisor.descriptor.vmx.Phrase




Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.hypervisor.descriptor.vmx.HAS_PYSTANDALONE
   dissect.hypervisor.descriptor.vmx.HAS_PYCRYPTODOME
   dissect.hypervisor.descriptor.vmx.CIPHER_KEY_SIZES
   dissect.hypervisor.descriptor.vmx.HMAC_MAP
   dissect.hypervisor.descriptor.vmx.PASS2KEY_MAP


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


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


.. py:data:: CIPHER_KEY_SIZES

.. py:data:: HMAC_MAP

.. py:data:: PASS2KEY_MAP

.. py:class:: VMX(attr: dict[str, str])

   .. py:attribute:: attr


   .. py:method:: parse(string: str) -> VMX
      :classmethod:


      Parse a VMX dictionary from a string.



   .. py:property:: encrypted
      :type: bool


      Return whether this VMX is encrypted.

      Encrypted VMXs will have both a ``encryption.keySafe`` and ``encryption.data`` value.
      The ``encryption.keySafe`` is a string encoded ``KeySafe``, which is made up of key locators.

      For example:

      .. code-block:: none

          vmware:key/list/(pair/(phrase/phrase_id/phrase_content,hmac,data),pair/(.../...,...,...))

      A ``KeySafe`` must be a list of ``Pairs``. Each ``Pair`` has a wrapped key, an HMAC type and encrypted data.
      It's implementation specific how to unwrap a key. E.g. a phrase is just PBKDF2. The unwrapped key
      can be used to unlock the encrypted ``Pair`` data. This will contain the final encryption key to decrypt
      the data in ``encryption.data``.

      So, in summary, to unseal a ``KeySafe``:

      - Parse ``KeySafe``
      - Iterate pairs
      - Unlock ``Pair``
      - Unwrap key (e.g. ``Phrase``)
      - Decrypt ``Pair`` data
      - Parse dictionary

      The terms for unwrapping, unlocking and unsealing are taken from VMware.


   .. py:method:: unlock_with_phrase(passphrase: str) -> None

      Unlock this VMX in-place with a passphrase if it's encrypted.

      This will load the ``KeySafe`` from the current dictionary and attempt to recover the encryption key
      from it using the given passphrase. This key is used to decrypt the encrypted VMX data.

      The dictionary is updated in-place with the encrypted VMX data.



   .. py:method:: disks() -> list[str]

      Return a list of paths to disk files



.. py:class:: KeySafe(locators: list[Pair])

   .. py:attribute:: locators


   .. py:method:: unseal_with_phrase(passphrase: str) -> bytes

      Unseal this ``KeySafe`` with a passphrase and return the decrypted key.



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


      Parse a ``KeySafe`` from a string.



.. py:class:: Pair(wrapped_key: Phrase, mac: str, data: bytes)

   .. py:attribute:: wrapped_key


   .. py:attribute:: mac


   .. py:attribute:: data


   .. py:method:: __repr__() -> str


   .. py:method:: has_phrase() -> bool

      Return whether this ``Pair`` is a ``Phrase`` pair.



   .. py:method:: unlock(*args, **kwargs) -> bytes

      Helper method to unlock this ``Pair`` for various wrapped keys.

      Currently only supports `Phrase`.



   .. py:method:: unlock_with_phrase(passphrase: str) -> bytes

      Unlock this ``Pair`` with a passphrase and return the decrypted data.



.. py:class:: Phrase(id: str, pass2key: str, cipher: str, rounds: int, salt: bytes)

   .. py:attribute:: id


   .. py:attribute:: pass2key


   .. py:attribute:: cipher


   .. py:attribute:: rounds


   .. py:attribute:: salt


   .. py:method:: __repr__() -> str


   .. py:method:: unwrap(passphrase: str) -> bytes

      Unwrap/generate the encryption key for a given passphrase.

      VMware calls this unwrapping, but really it's a KDF with the properties of this ``Phrase``.