perl/keyring/auto / README

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

    Version 0.2602

    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::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.
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.