maestral.keyring

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

Module Contents

class maestral.keyring.TokenType[source]

Bases: enum.Enum

Enumeration of token types

Offline = offline[source]

Long-lived refresh-token to generate short-lived access tokens

Legacy = legacy[source]

Long-lived access token

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(self)[source]

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

Return type

KeyringBackend | None

set_keyring_backend(self, 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 (KeyringBackend | None) – Keyring backend to use.

Return type

None

property loaded(self)[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_type(self)[source]

The type of token (read only). If ‘legacy’, we have a long-lived access token. If ‘offline’, we have a long-lived refresh token which can be used to generate new short-lived access tokens.

Return type

TokenType | None

property token(self)[source]

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

Return type

str | None

property account_id(self)[source]

The saved account id (read only).

Return type

str | None

load_creds(self)[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.

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(self, account_id, token, token_type)[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.

  • token_type (TokenType) – The type of access token.

Return type

None

delete_creds(self)[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