Encryped Data

Keyring [1] is the package used to manage encryption.

To save a secret …

from jsonconfig import Config

with Config('myapp') as cfg:
    cfg.pwd.some_user = 'some value'

To retrieve the secret …

with Config('myapp') as cfg:
    password = cfg.pwd.some_user

Default Behavior

The default behavior is to select the most secure backend supported by the user’s platform. To give you an idea, the following Keyring backends would likely be returned:

Mac OS X:
Keychain [2]
Unix (with secretstorage installed):
Freedesktop Secret Service [3]
Unix (with dbus installed):
kwallet [4]
Windows:
Windows Credential Locker [5]

How-to Set the Service Name

You can think of the service name as the folder where Keyring stores the key/value pair. By default the service name is set the current logged in username + ‘_’ + app_name. You can override this behavior by explicitly setting the service_name in the context manager.

with Config('my_app_name', service_name='my_service_name') as cfg:
    cfg.pwd.secret = 'Open Seasame!'

Enabling and Disabling the Keyring

The keyring keyword argument controls this.

True
This is the default. Enable Keyring and use the default backend.
False

Disable the Keyring. The Keyring will not be initalized and the pwd attribute will not be available.

with Config('myapp', keyring=False) as cfg:
    cfg.data = 'Some value'
KeyringConfig

This shortcut will enable Keyring and disable data configurations. The data attributed will not be available.

from jsonconfig import Keyring

with Keyring(‘myapp’) as vault:
vault.pwd.key1 = ‘a secret’ vault.pwd.key2 = ‘another secret’

Manually Setting the Keyring Backend

Of course, you or the user are free to override the defaults. The user can also change their Keyring backend preferences system-wide from the command-line or via configuration files. JSON Config will then use the user’s preferred Keyring backend unless told otherwise.

From the Command Line

$ keyring set system username
<enter hidden password for 'username' in 'system'>

$ keyring get system username
password

From inside JSON Config

keyring.backends

The keyring option accepts a keyring.backends class.

import keyring.backends

from jsonconfig import Config

backend = keyring.backends.Windows.WinVaultKeyring
with Config('myapp', keyring=backend) as cfg:
    cfg.pwd.some_key = 'a secret'
Keyring Backend Name

The keyring option accepts a keyring backend name.

import keyring.backends

from jsonconfig import Config

with Config('myapp', keyring='WinVaultKeyring') as cfg:
    cfg.pwd.some_key = 'a secret'
Valid Keyring names are:
  • OS_X
  • WIndows
  • kwallet
  • SecretService

How it Works

Keyring describes setting a password as follows: set_password(service, username, password). Username and password do not have to contain user names and password, they are not special; JSON Config treats username and password as key and value.

When you set a pwd key to a value it calls set_password(service_name, key, value).

When you get a value from a pwd key it calls get_password(service_name, key).