Class PasswordManager

Known Subclasses:

StreamSASLMixIn

Base class for password managers.

Password manager is an object responsible for providing or verification
of authentication credentials.

All the methods of `PasswordManager` class may be overriden in derived
classes for specific authentication and authorization policy.

Initialize a `PasswordManager` object.

Check if the authenticated entity is allowed to use given
authorization id.

[server only]

By default return `True` if the `authzid` is `None` or empty or it is
equal to extra_info["username"] (if the latter is present).

:Parameters:
    - `authzid`: an authorization id.
    - `extra_info`: information about an entity got during the
      authentication process. This is a mapping with arbitrary,
      mechanism-dependent items. Common keys are 'username' or
      'realm'.
:Types:
    - `authzid`: `unicode`
    - `extra_info`: mapping

:return: `True` if the authenticated entity is authorized to use
    the provided authorization id.
:returntype: `bool`

Check the password validity.

[server only]

Used by plain-text authentication mechanisms.

Retrieve a "plain" password for the `username` and `realm` using
`self.get_password` and compare it with the password provided.

May be overrided e.g. to check the password against some external
authentication mechanism (PAM, LDAP, etc.).

:Parameters:
    - `username`: the username for which the password verification is
      requested.
    - `password`: the password to verify.
    - `realm`: the authentication realm for which the password
      verification is requested.
:Types:
    - `username`: `unicode`
    - `password`: `unicode`
    - `realm`: `unicode`

:return: `True` if the password is valid.
:returntype: `bool`

Choose an authentication realm from the list provided by the server.

[client only]

By default return the first realm from the list or `None` if the list
is empty.

:Parameters:
    - `realm_list`: the list of realms provided by a server.
:Types:
    - `realm_list`: sequence of `unicode`

:return: the realm chosen.
:returntype: `unicode`

Generate a random string for digest authentication challenges.

The string should be cryptographicaly secure random pattern.

:return: the string generated.
:returntype: `str`

Get the password for user authentication.

[both client or server]

By default returns (None, None) providing no password. Should be
overriden in derived classes.

:Parameters:
    - `username`: the username for which the password is requested.
    - `realm`: the authentication realm for which the password is
      requested.
    - `acceptable_formats`: a sequence of acceptable formats of the
      password data. Could be "plain", "md5:user:realm:password" or any
      other mechanism-specific encoding. This allows non-plain-text
      storage of passwords. But only "plain" format will work with
      all password authentication mechanisms.
:Types:
    - `username`: `unicode`
    - `realm`: `unicode`
    - `acceptable_formats`: sequence of `str`

:return: the password and its encoding (format).
:returntype: `unicode`,`str` tuple.

Get available realms list.

[server only]

:return: a list of realms available for authentication. May be empty --
    the client may choose its own realm then or use no realm at all.
:returntype: `list` of `unicode`

Return the host name for DIGEST-MD5 'digest-uri' field.

Should be overriden in derived classes.

:return: the host name ("unknown" by default)

Return the service name for DIGEST-MD5 'digest-uri' field.

Should be overriden in derived classes.

:return: the service name or `None` (which is the default).

Return the service type for DIGEST-MD5 'digest-uri' field.

Should be overriden in derived classes.

:return: the service type ("unknown" by default)