core.bones.password
===================

.. py:module:: core.bones.password

.. autoapi-nested-parse::

   The PasswordBone class is a specialized version of the StringBone class designed to handle password
   data. It hashes the password data before saving it to the database and prevents it from being read
   directly. The class also includes various tests to determine the strength of the entered password.



Attributes
----------

.. autoapisummary::

   core.bones.password.PBKDF2_DEFAULT_ITERATIONS


Classes
-------

.. autoapisummary::

   core.bones.password.PasswordBone


Functions
---------

.. autoapisummary::

   core.bones.password.encode_password


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

.. py:data:: PBKDF2_DEFAULT_ITERATIONS
   :value: 600000


.. py:function:: encode_password(password, salt, iterations = PBKDF2_DEFAULT_ITERATIONS, dklen = 42)

   Decodes a pashword and return the hash and meta information as hash


.. py:class:: PasswordBone(*, descr = 'Password', test_threshold = 4, tests = tests, raw = False, **kwargs)

   Bases: :py:obj:`viur.core.bones.string.StringBone`


   A specialized subclass of the StringBone class designed to handle password data.

   The PasswordBone hashes the password before saving it to the database and prevents it from
   being read directly. It also includes various tests to determine the strength of the entered
   password.

   Initializes a new PasswordBone.

   :param test_threshold: The minimum number of tests the password must pass.
   :param password_tests: Defines separate tests specified as tuples of regex, hint and required-flag.
   :param raw: Don't encode password's hash when reading from client, just save the provided string.


   .. py:attribute:: type
      :value: 'password'


      A string representing the bone type, which is "password" in this case.



   .. py:attribute:: saltLength
      :value: 13



   .. py:attribute:: tests
      :type:  Iterable[Iterable[Tuple[str, str, bool]]]

      Provides tests based on regular expressions to test the password strength.

      Note: The provided regular expressions have to produce exactly the same results in Python and JavaScript.
            This requires that some feature either cannot be used, or must be rewritten to match on both engines.



   .. py:attribute:: test_threshold
      :value: 4



   .. py:attribute:: raw
      :value: False



   .. py:method:: isInvalid(value)

      Determines if the entered password is invalid based on the length and strength requirements.
      It checks if the password is empty, too short, or too weak according to the password tests
      specified in the class.

      :param str value: The password to be checked.
      :return: True if the password is invalid, otherwise False.
      :rtype: bool



   .. py:method:: fromClient(skel, name, data)

      Processes the password field from the client data, validates it, and stores it in the
      skeleton instance after hashing. This method performs several checks, such as ensuring that
      the password field is present in the data, that the password is not empty, and that it meets
      the length and strength requirements. If any of these checks fail, a ReadFromClientError is
      returned.

      :param SkeletonInstance skel: The skeleton instance to store the password in.
      :param str name: The name of the password field.
      :param dict data: The data dictionary containing the password field value.
      :return: None if the password is valid, otherwise a list of ReadFromClientErrors.
      :rtype: Union[None, List[ReadFromClientError]]



   .. py:method:: serialize(skel, name, parentIndexed)

      Processes and stores the password field from the client data into the skeleton instance after
      hashing and validating it. This method carries out various checks, such as:

      * Ensuring that the password field is present in the data.
      * Verifying that the password is not empty.
      * Confirming that the password meets the length and strength requirements.

      If any of these checks fail, a ReadFromClientError is returned.

      :param SkeletonInstance skel: The skeleton instance where the password will be stored as a
          hashed value along with its salt.
      :param str name: The name of the password field used to access the password value in the
          data dictionary.
      :param dict data: The data dictionary containing the password field value, typically
          submitted by the client.
      :return: None if the password is valid and successfully stored in the skeleton instance;
          otherwise, a list of ReadFromClientErrors containing detailed information about the errors.
      :rtype: Union[None, List[ReadFromClientError]]



   .. py:method:: unserialize(skeletonValues, name)

      This method does not unserialize password values from the datastore. It always returns False,
      indicating that no password value will be unserialized.

      :param dict skeletonValues: The dictionary containing the values from the datastore.
      :param str name: The name of the password field.
      :return: False, as no password value will be unserialized.
      :rtype: bool



   .. py:method:: structure()

      Describes the bone and its settings as an JSON-serializable dict.
      This function has to be implemented for subsequent, specialized bone types.



   .. py:method:: _atomic_dump(value)

      One atomic value of the bone.