view release on metacpan or  search on metacpan

README  view on Meta::CPAN

NAME

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

VERSION

    Version 1.0000

SYNOPSIS

    Passwd::Keyring is about securely preserving passwords and other
    sensitive data (for example API keys, OAuth tokens etc) 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, program options, and user
    configuration.

        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");
        unless($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 user need not be prompted again.

    The choice can be impacted by configuration file, some environment
    variables and/or additional parameters, see "BACKEND SELECTION
    CRITERIA".

    One can skip this module and be explicit if he or she knows which
    keyring is to be used:

        use Passwd::Keyring::Gnome;
        my $keyring = Passwd::Keyring::Gnome->new();
        # ... from there as above

SUBROUTINES/METHODS

 get_keyring

        my $ring = get_keyring()
    
        my $ring = get_keyring(app=>'MyApp', group=>'SyncPasswords');
    
        my $ring = get_keyring(app=>'MyApp', group=>'Uploads',
                               config=>"$ENV{HOME}/.passwd-keyring-business.cfg");
    
        my $ring = get_keyring(app=>'MyApp', group=>'Scrappers',
                               prefer=>['Gnome', 'PWSafe3'],
                               forbid=>['KDEWallet']);
    
        my $ring = get_keyring(app=>'MyApp', group=>'Scrappers',
                               force=>['KDEWallet']);
    
        my $ring = get_keyring(app=>'MyApp', group=>'SyncPasswords',
                               %backend_specific_options);

    Returns the keyring object most appropriate for the current system (and
    matching specified criteria, and applying user configuration) and
    initiates it.

    The function inspects context the application runs in (operating
    system, presence of GUI sessions etc), decides which backends seem
    suitable and in what order of preference, then tries all suitable
    backends and returns first succesfully loaded and initialized (or