Marcin Kasperski
and 1 contributors


Passwd::Keyring::Auto - interface to secure password storage(s)


Version 0.2701


Passwd::Keyring is about securely preserving passwords and similar sensitive data applications use in backends like Gnome Keyring, KDE Wallet, OSX/Keychain etc.

While modules like Passwd::Keyring::Gnome handle specific backends, Passwd::Keyring::Auto tries to pick the best backend available, considering the current desktop environment.

    use Passwd::Keyring::Auto;  # get_keyring

    my $keyring = get_keyring(app=>"My super scraper", group=>"Social passwords");

    my $username = "someuser";
    my $password = $keyring->get_password($username, "");
    if(! $password) {
        # ... somehow interactively prompt for password
        $keyring->set_password($username, $password, "");
    login_somewhere_using($username, $password);
    if( password_was_wrong ) {
        $keyring->clear_password($username, "");

If any secure backend is available, password is preserved for successive runs, and users need not be prompted.

The choice can be impacted by some environment variables, see get_keyring documentation for details.

Finally, one can skip this module and be explicit:

    use Passwd::Keyring::Gnome;
    my $keyring = Passwd::Keyring::Gnome->new();
    # ... and so on





    my $ring = get_keyring()

    my $ring = get_keyring(app=>'symbolic application name', group=>'symbolic group/folder/.. name');

    my $ring = get_keyring(app=>'...', group=>'...', %backend_specific_options);

Returns the keyring object most appropriate for the current system. Passess all options received to this backend. See Passwd::Keyring::Auto::KeyringAPI for available operations on keyring and their semantic.

Note: setting environment variable PASSWD_KEYRING_AUTO_DEBUG causes the routine to print to stderr details about tried and selected keyrings.

The default choice can be influenced by environment variables:

- PASSWD_KEYRING_AUTO_FORBID - name or space separated names of keyrings which can't be used, for example Gnome or Gnome KDEWallet (note: Memory can't be forbidden, but is always last)

- PASSWD_KEYRING_AUTO_PREFER - name or space separated names of keyrings to prefer


Passwd::Keyring::Auto::KeyringAPI describes backends API in detail.


Marcin Kasperski


Please report any bugs or feature requests to issue tracker at


You can find documentation for this module with the perldoc command.

    perldoc Passwd::Keyring::Auto

You can also look for information at:

Source code is tracked at:


Copyright 2012 Marcin Kasperski.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See for more information.