:py:mod:`dissect.target.plugins.os.windows.dpapi.crypto`
========================================================

.. py:module:: dissect.target.plugins.os.windows.dpapi.crypto




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

Classes
~~~~~~~

.. autoapisummary::

   dissect.target.plugins.os.windows.dpapi.crypto.CipherAlgorithm
   dissect.target.plugins.os.windows.dpapi.crypto.HashAlgorithm



Functions
~~~~~~~~~

.. autoapisummary::
   :nosignatures:

   dissect.target.plugins.os.windows.dpapi.crypto.pbkdf2
   dissect.target.plugins.os.windows.dpapi.crypto.dpapi_hmac
   dissect.target.plugins.os.windows.dpapi.crypto.crypt_session_key_type1
   dissect.target.plugins.os.windows.dpapi.crypto.crypt_session_key_type2
   dissect.target.plugins.os.windows.dpapi.crypto.derive_password_hash



Attributes
~~~~~~~~~~

.. autoapisummary::

   dissect.target.plugins.os.windows.dpapi.crypto.HAS_CRYPTO
   dissect.target.plugins.os.windows.dpapi.crypto.CIPHER_ALGORITHMS
   dissect.target.plugins.os.windows.dpapi.crypto.HASH_ALGORITHMS


.. py:data:: HAS_CRYPTO
   :value: True


.. py:data:: CIPHER_ALGORITHMS
   :type:  dict[int | str, CipherAlgorithm]

.. py:data:: HASH_ALGORITHMS
   :type:  dict[int | str, HashAlgorithm]

.. py:class:: CipherAlgorithm

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


   .. py:attribute:: name
      :type:  str


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


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


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


   .. py:method:: __init_subclass__()
      :classmethod:



   .. py:method:: from_id(id: int) -> Self
      :classmethod:



   .. py:method:: from_name(name: str) -> Self
      :classmethod:



   .. py:method:: derive_key(key: bytes, hash_algorithm: HashAlgorithm) -> bytes

      Mimics the corresponding native Microsoft function.

      .. rubric:: References

      - https://github.com/tijldeneut/DPAPIck3/blob/main/dpapick3/crypto.py#L185



   .. py:method:: fixup_key(key: bytes) -> bytes


   .. py:method:: decrypt_with_hmac(data: bytes, key: bytes, iv: bytes, hash_algorithm: HashAlgorithm, rounds: int) -> bytes


   .. py:method:: decrypt(data: bytes, key: bytes, iv: bytes | None = None) -> bytes
      :abstractmethod:



.. py:class:: HashAlgorithm

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


   .. py:attribute:: name
      :type:  str


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


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


   .. py:method:: __init_subclass__()
      :classmethod:



   .. py:method:: from_id(id: int) -> Self
      :classmethod:



   .. py:method:: from_name(name: str) -> Self
      :classmethod:



.. py:function:: pbkdf2(passphrase: bytes, salt: bytes, key_len: int, iterations: int, digest: str = 'sha1') -> bytes

   Implementation of PBKDF2 that allows specifying digest algorithm.

   Returns the corresponding expanded key which is ``key_len`` long.


.. py:function:: dpapi_hmac(pwd_hash: bytes, hmac_salt: bytes, value: bytes, hash_algorithm: HashAlgorithm) -> bytes

   Internal function used to compute HMACs of DPAPI structures.


.. py:function:: crypt_session_key_type1(master_key: bytes, nonce: bytes | None, hash_algorithm: HashAlgorithm, entropy: bytes | None = None, strong_password: str | None = None, smart_card_secret: bytes | None = None, verify_blob: bytes | None = None) -> bytes

   Computes the decryption key for Type1 DPAPI blob, given the master key and optional information.

   This implementation relies on a faulty implementation from Microsoft that does not respect the HMAC RFC.
   Instead of updating the inner pad, we update the outer pad.
   This algorithm is also used when checking the HMAC for integrity after decryption.

   :param master_key: Decrypted master key (should be 64 bytes long).
   :param nonce: This is the nonce contained in the blob or the HMAC in the blob (integrity check).
   :param hash_algorithm: A :class:`HashAlgorithm` to use for calculating block sizes.
   :param entropy: This is the optional entropy from ``CryptProtectData()`` API.
   :param strong_password: Optional password used for decryption or the blob itself.
   :param smart_card_secret: Optional MS Next Gen Crypto secret (e.g. from PIN code).
   :param verify_blob: Optional encrypted blob used for integrity check.

   :returns: The decryption key.


.. py:function:: crypt_session_key_type2(masterkey: bytes, nonce: bytes, hash_algorithm: HashAlgorithm, entropy: bytes | None = None, strong_password: str | None = None, smart_card_secret: bytes | None = None, verify_blob: bytes | None = None) -> bytes

   Computes the decryption key for Type2 DPAPI blob, given the masterkey and optional information.

   This implementation relies on an RFC compliant HMAC implementation.
   This algorithm is also used when checking the HMAC for integrity after decryption.

   :param master_key: Decrypted master key (should be 64 bytes long).
   :param nonce: This is the nonce contained in the blob or the HMAC in the blob (integrity check).
   :param hash_algo: A :class:`HashAlgorithm` to use for calculating block sizes.
   :param entropy: This is the optional entropy from ``CryptProtectData()`` API.
   :param strong_password: Optional password used for decryption or the blob itself.
   :param smart_card_secret: Optional MS Next Gen Crypto secret (e.g. from PIN code). Only for API compatibility.
   :param verify_blob: Optional encrypted blob used for integrity check.

   :returns: The decryption key.


.. py:function:: derive_password_hash(password_hash: bytes, user_sid: str, digest: str = 'sha1') -> bytes

   Internal use. Computes the encryption key from a user's password hash.