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

VERSION
    Version 0.2701

SYNOPSIS
    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, "mylostspace.com");
        if(! $password) {
            # ... somehow interactively prompt for password
            $keyring->set_password($username, $password, "mylostspace.com");
        }
        login_somewhere_using($username, $password);
        if( password_was_wrong ) {
            $keyring->clear_password($username, "mylostspace.com");
        }

    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

EXPORT
    get_keyring

SUBROUTINES/METHODS
  get_keyring
        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

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

AUTHOR
    Marcin Kasperski

BUGS
    Please report any bugs or feature requests to issue tracker at
    https://bitbucket.org/Mekk/perl-keyring-auto.

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

        perldoc Passwd::Keyring::Auto

    You can also look for information at:

    http://search.cpan.org/~mekk/Passwd-Keyring-Auto/

    Source code is tracked at:

    https://bitbucket.org/Mekk/perl-keyring-auto

LICENSE AND COPYRIGHT
    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 http://dev.perl.org/licenses/ for more information.