Passwd::Keyring::Auto - interface to secure password storage(s)
Version 0.72
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"); 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 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
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 croaks if there is none). See "BACKEND SELECTION CRITERIA" for info about criteria used.
All parameters are optional, but it is strongly recommended to set app and group.
app
group
General parameters:
Symbolic application name, which - depending on backend - may appear in interactive prompts (like dialog box "Application APP-NAME wants to access secure data..." popped up by KDE Wallet) and may be preserved as comment ("Created by ...") in secure storage (so may be seen in GUI password management apps like seahorse). Also, if config file is in use, it can override some settings on per-application basis.
The name of the passwords folder. Can be visualised as folder or group by some GUIs (seahorse, pwsafe3) but it's most important role is to let one separate passwords used for different purposes. A few apps/scripts will share passwords if they use the same group name, but will use different and unrelated passwords if they specify different group.
Config file location.
Parameters impacting backend selection (usually not recommended as they limit user choice, but hardcode choices if you like):
Try only given backend and nothing else. Expects short backend name. For example force='Gnome'> means Passwd::Keyring::Gnome is to be used and nothing else.
force=
Try this/those backends first, and in the specified order (and try them even if by default they are not considered suitable for OS in use).
For example prefer=['OSXKeychain', 'KDEWallet']> asks module to try Passwd::Keyring::OSXKeychain first, then Passwd::Keyring::KDEWallet, then other options (if any) in module own preference.
prefer=
Never use specified backend(s).
For example forbid=['Gnome', 'KDEWallet']> will cause method not to consider those GUI keyrings even if we run on Linux and have Gnome or KDE session active.
forbid=
Backend-specific parameters:
All other parameters are passed as such to actual keyring backend. To check whether/which may be used, consult backends documentation. Backends ignore params they do not understand, so some superset of possibly useful params is OK.
It is recommended to use configuration file instead.
The function in it's simplest form should not fail (it falls back to Passwd::Keyring::Memory if everything else fails), but it may croak if some keyring is enforced or if Memory is forbidden or uninstalled.
See Passwd::Keyring::Auto::KeyringAPI for operations available on keyring objects.
The recommended way to impact backend selection on per-system (and user) basis is to use configuration file, which let the user set default keyring selection rules, and per-application overrides.
It's initial version can be created by passwd_keyring script:
passwd_keyring config_create
and edited afterwards.
See "BACKEND SELECTION CRITERIA" for info how configuration settings relate to other backend selection methods.
By default, config file is looked in ~/.passwd-keyring.cfg on Linux/Unix and ~/Local Settings/Application Data/.passwd-keyring.cfg on Windows (more exactly: .passwd-keyring.cfg in directory reported by my_data function from File::HomeDir).
~/.passwd-keyring.cfg
~/Local Settings/Application Data/.passwd-keyring.cfg
.passwd-keyring.cfg
my_data
Environment variable PASSWD_KEYRING_CONFIG can be used to override this setting (and should contain path of the configuration file). Also, config parameter can be used in get_keyring method (and takes precedence even over env variable).
PASSWD_KEYRING_CONFIG
config
get_keyring
Note that while it is OK not to have config file at all, but it is an error (and causes exception) to have non-existing or inaccessible file pointed by parameter or environment variable.
Example:
; Default settings prefer=KDEWallet PWSafe3 Memory forbid=Gnome PWSafe3.file=~/passwd-keyring.pwsafe3 ; Overrides for app named WebScrapers [WebScrapers] force=Gnome ; Overrides for app named XYZTests [XYZTests] force=PWSafe3 PWSafe3.file=~/tests/xyz/passwd-keyring-tokens.pwsafe3
prefer, forbid and force define appropriate steering values, as documented in Passwd::Keyring::Auto. Space is used to separate multiple values.
prefer
forbid
force
; can be used to start line comments.
;
The following environment variables can be used to impact the module behaviour.
General configuration variables:
Defines location of the config file.
PASSWD_KEYRING_DEBUG
Log on stderr details about tried and selected backends (and errors faced while they are tried).
Backend-selection variables (see "BACKEND SELECTION CRITERIA" for info how they relate to other methods and note that using configuration file is usually recommended over setting those variables):
PASSWD_KEYRING_FORCE
Use given backend and nothing else. For example, by setting PASSWD_KEYRING_FORCE=KDEWallet user may enforce use of Passwd::Keyring::KDEWallet.
PASSWD_KEYRING_FORCE=KDEWallet
This variable is completely ignored if force parameter was specified, and causes runtime error if specified backend is not present, not working, or present on the forbid list.
PASSWD_KEYRING_FORBID
Space separated list of backends to forbid, for example PASSWD_KEYRING_FORBID="Gnome KDEWallet".
PASSWD_KEYRING_FORBID="Gnome KDEWallet"
Ignored if force parameter was specified, otherwise works as this param.
PASSWD_KEYRING_PREFER
Space separated names of backends to prefer.
Ignored if prefer parameter was specified, otherwise works as this param.
Backend selection is organized around 3 steering parameters: force, forbid, and prefer. For each of those, the value is looked in the following places (first found is returned):
PASSWD_KEYRING_...
Each param is calculated separately, so one can have prefer initialized from hardcoded value, forbid taken from the config file and force defined by PASSWD_KEYRING_FORCE environment variable. This may sometimes be confusing so use sparingly (and limit to config file unless you really have reason to do otherwise).
Once calculated, those params are used in the following way:
The following library defaults are used:
Passwd::Keyring::Auto::KeyringAPI describes methods available on keyring objects and provides some additional detail on keyring construction.
Marcin Kasperski
Please report any bugs or feature requests to issue tracker at https://bitbucket.org/Mekk/perl-keyring-auto.
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
Copyright 2012-2015 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.
To install Passwd::Keyring::Auto, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Passwd::Keyring::Auto
CPAN shell
perl -MCPAN -e shell install Passwd::Keyring::Auto
For more information on module installation, please visit the detailed CPAN module installation guide.