maestral.keyring#

This module is responsible for authorization and token store in the system keyring.

Module Contents#

class maestral.keyring.CredentialStorage(config_name)[source]#

Provides a threadsafe interface to store credentials in a system keyring

CredentialStorage provides token store in the preferred system keyring. Supported keyring backends are, in order of preference:

  • macOS Keychain

  • Any keyring implementing the SecretService Dbus specification

  • KWallet

  • Plain text storage

Note

Once the token has been stored with a keyring backend, that backend will be saved in the config file and remembered until deleting the credentials.

Warning

Unlike macOS Keychain, Gnome Keyring and KWallet do not support app-specific access to passwords. If the user unlocks those keyrings, we and any other application in the same user session get access to all saved passwords.

Parameters:

config_name (str) – Name of maestral config.

property keyring: keyring.backend.KeyringBackend | None[source]#

The keyring backend currently being used to store auth tokens. Will be None if we are not linked.

Return type:

keyring.backend.KeyringBackend | None

property loaded: bool[source]#

Whether we have already loaded the credentials. This will be true after calling load_creds() or accessing the any of the auth credentials through instance properties.

Return type:

bool

property token: str | None[source]#

The saved token (read only). This call will block until the keyring is unlocked.

Return type:

str | None

property account_id: str | None[source]#

The saved account id (read only).

Return type:

str | None

set_keyring_backend(ring)[source]#

Enforce usage of a particular keyring backend. If not called, the best backend will be selected depending on the platform. Do not change backends after saving credentials.

Parameters:

ring (keyring.backend.KeyringBackend | None) – Keyring backend to use.

Return type:

None

load_creds()[source]#

Loads auth token from system keyring. This will be called automatically when accessing the token property. This call will block until the keyring is unlocked or unlocking is declined by the user.

Raises:

KeyringAccessError – if the system keyring is locked or otherwise cannot be accessed (for example if the app bundle signature has been invalidated).

Return type:

None

save_creds(account_id, token)[source]#

Saves the auth token to system keyring. Falls back to plain text storage if the user denies access to keyring.

Parameters:
  • account_id (str) – The account ID.

  • token (str) – The access token.

Return type:

None

delete_creds()[source]#

Deletes auth token from system keyring.

Raises:

KeyringAccessError – if the system keyring is locked or otherwise cannot be accessed (for example if the app bundle signature has been invalidated).

Return type:

None