File Coverage

blib/lib/Passwd/Keyring/Auto.pm
Criterion Covered Total %
statement 17 17 100.0
branch n/a
condition n/a
subroutine 6 6 100.0
pod 1 1 100.0
total 24 24 100.0


line stmt bran cond sub pod time code
1             package Passwd::Keyring::Auto;
2              
3 7     7   138659 use warnings;
  7         13  
  7         212  
4 7     7   26 use strict;
  7         11  
  7         182  
5 7     7   29 use base 'Exporter';
  7         12  
  7         716  
6             our @EXPORT = qw(get_keyring);
7 7     7   33 use Carp;
  7         9  
  7         421  
8 7     7   2631 use Passwd::Keyring::Auto::Chooser;
  7         15  
  7         1020  
9              
10             =head1 NAME
11              
12             Passwd::Keyring::Auto - interface to secure password storage(s)
13              
14             =head1 VERSION
15              
16             Version 0.71
17              
18             =cut
19              
20             our $VERSION = '0.71';
21              
22             =head1 SYNOPSIS
23              
24             Passwd::Keyring is about securely preserving passwords and other
25             sensitive data (for example API keys, OAuth tokens etc) in backends
26             like Gnome Keyring, KDE Wallet, OSX/Keychain etc.
27              
28             While modules like Passwd::Keyring::Gnome handle specific backends,
29             Passwd::Keyring::Auto tries to pick the best backend available,
30             considering the current desktop environment, program options, and user
31             configuration.
32              
33             use Passwd::Keyring::Auto; # get_keyring
34              
35             my $keyring = get_keyring(app=>"My super scraper", group=>"Social passwords");
36              
37             my $username = "someuser";
38             my $password = $keyring->get_password($username, "mylostspace.com");
39             if(! $password) {
40             # ... somehow interactively prompt for password
41             $keyring->set_password($username, $password, "mylostspace.com");
42             }
43             login_somewhere_using($username, $password);
44             if( password_was_wrong ) {
45             $keyring->clear_password($username, "mylostspace.com");
46             }
47              
48             If any secure backend is available, password is preserved
49             for successive runs, and user need not be prompted again.
50              
51             The choice can be impacted by configuration file, some environment
52             variables and/or additional parameters, see L</BACKEND SELECTION CRITERIA>.
53              
54             One can skip this module and be explicit if he or she knows which
55             keyring is to be used:
56              
57             use Passwd::Keyring::Gnome;
58             my $keyring = Passwd::Keyring::Gnome->new();
59             # ... from there as above
60              
61             =head1 SUBROUTINES/METHODS
62              
63             =head2 get_keyring
64              
65             my $ring = get_keyring()
66              
67             my $ring = get_keyring(app=>'MyApp', group=>'SyncPasswords');
68              
69             my $ring = get_keyring(app=>'MyApp', group=>'Uploads',
70             config=>"$ENV{HOME}/.passwd-keyring-business.cfg");
71              
72             my $ring = get_keyring(app=>'MyApp', group=>'Scrappers',
73             prefer=>['Gnome', 'PWSafe3'],
74             forbid=>['KDEWallet']);
75              
76             my $ring = get_keyring(app=>'MyApp', group=>'Scrappers',
77             force=>['KDEWallet']);
78              
79             my $ring = get_keyring(app=>'MyApp', group=>'SyncPasswords',
80             %backend_specific_options);
81              
82             Returns the keyring object most appropriate for the current system
83             (and matching specified criteria, and applying user configuration) and
84             initiates it.
85              
86             The function inspects context the application runs in (operating
87             system, presence of GUI sessions etc), decides which backends seem
88             suitable and in what order of preference, then tries all suitable
89             backends and returns first succesfully loaded and initialized (or
90             croaks if there is none). See L</BACKEND SELECTION CRITERIA> for
91             info about criteria used.
92              
93             All parameters are optional, but it is strongly recommended to set
94             C<app> and C<group>.
95              
96             General parameters:
97              
98             =over 4
99              
100             =item app => 'App Name'
101              
102             Symbolic application name, which - depending on backend - may appear
103             in interactive prompts (like dialog box "Application APP-NAME wants
104             to access secure data..." popped up by KDE Wallet) and may be
105             preserved as comment ("Created by ...") in secure storage (so may be
106             seen in GUI password management apps like seahorse). Also, if config
107             file is in use, it can override some settings on per-application basis.
108              
109             =item group => 'PasswordFolder'
110              
111             The name of the passwords folder. Can be visualised as folder or group
112             by some GUIs (seahorse, pwsafe3) but it's most important role is to
113             let one separate passwords used for different purposes. A few
114             apps/scripts will share passwords if they use the same group name, but
115             will use different and unrelated passwords if they specify different
116             group.
117              
118             =item config => "/some/where/passwd_keyring.cfg"
119              
120             Config file location.
121              
122             =back
123              
124             Parameters impacting backend selection (usually not recommended as
125             they limit user choice, but hardcode choices if you like):
126              
127             =over 4
128              
129             =item force => 'Backend'
130              
131             Try only given backend and nothing else. Expects short backend name.
132             For example C<force=>'Gnome'> means L<Passwd::Keyring::Gnome> is to be
133             used and nothing else.
134              
135             =item prefer=>'Backend' or prefer => ['Backend1', 'Backend2', ...]
136              
137             Try this/those backends first, and in the specified order (and try them
138             even if by default they are not considered suitable for OS in use).
139              
140             For example C<prefer=>['OSXKeychain', 'KDEWallet']> asks module to try
141             L<Passwd::Keyring::OSXKeychain> first, then
142             L<Passwd::Keyring::KDEWallet>, then other options (if any) in module
143             own preference.
144              
145             =item forbid=>'Backend' or forbid => ['Backend1', 'Backend2', ...]
146              
147             Never use specified backend(s).
148              
149             For example C<forbid=>['Gnome', 'KDEWallet']> will cause method not to
150             consider those GUI keyrings even if we run on Linux and have Gnome or
151             KDE session active.
152              
153             =back
154              
155             Backend-specific parameters:
156              
157             =over 4
158              
159             =item other parameters
160              
161             All other parameters are passed as such to actual keyring backend.
162             To check whether/which may be used, consult backends documentation.
163             Backends ignore params they do not understand, so some superset
164             of possibly useful params is OK.
165              
166             It is recommended to use configuration file instead.
167              
168             =back
169              
170             The function in it's simplest form should not fail (it falls back to
171             L<Passwd::Keyring::Memory> if everything else fails), but it may croak
172             if some keyring is enforced or if Memory is forbidden or uninstalled.
173              
174             =head1 KEYRING METHODS
175              
176             See L<Passwd::Keyring::Auto::KeyringAPI> for operations available on
177             keyring objects.
178              
179             =head1 CONFIGURATION FILE
180              
181             The recommended way to impact backend selection on per-system (and
182             user) basis is to use configuration file, which let the user set
183             default keyring selection rules, and per-application overrides.
184              
185             It's initial version can be created by L<passwd_keyring> script:
186              
187             passwd_keyring config_create
188              
189             and edited afterwards.
190              
191             See L</BACKEND SELECTION CRITERIA> for info how configuration settings
192             relate to other backend selection methods.
193              
194             =head2 CONFIGURATION FILE LOCATION
195              
196             By default, config file is looked in C<~/.passwd-keyring.cfg> on
197             Linux/Unix and C<~/Local Settings/Application Data/.passwd-keyring.cfg>
198             on Windows (more exactly: C<.passwd-keyring.cfg> in directory reported by
199             C<my_data> function from L<File::HomeDir>).
200              
201             Environment variable C<PASSWD_KEYRING_CONFIG> can be used to
202             override this setting (and should contain path of the configuration
203             file). Also, C<config> parameter can be used in C<get_keyring> method
204             (and takes precedence even over env variable).
205              
206             Note that while it is OK not to have config file at all, but it is an
207             error (and causes exception) to have non-existing or inaccessible file
208             pointed by parameter or environment variable.
209              
210             =head2 CONFIGURATION FILE SYNTAX
211              
212             Example:
213              
214             ; Default settings
215             prefer=KDEWallet PWSafe3 Memory
216             forbid=Gnome
217             PWSafe3.file=~/passwd-keyring.pwsafe3
218              
219             ; Overrides for app named WebScrapers
220             [WebScrapers]
221             force=Gnome
222              
223             ; Overrides for app named XYZTests
224             [XYZTests]
225             force=PWSafe3
226             PWSafe3.file=~/tests/xyz/passwd-keyring-tokens.pwsafe3
227              
228             C<prefer>, C<forbid> and C<force> define appropriate steering values,
229             as documented in L<Passwd::Keyring::Auto>. Space is used to separate
230             multiple values.
231              
232             C<;> can be used to start line comments.
233              
234             =head1 ENVIRONMENT VARIABLES
235              
236             The following environment variables can be used to impact the module
237             behaviour.
238              
239             General configuration variables:
240              
241             =over 4
242              
243             =item C<PASSWD_KEYRING_CONFIG>
244              
245             Defines location of the config file.
246              
247             =item C<PASSWD_KEYRING_DEBUG>
248              
249             Log on stderr details about tried and selected backends (and errors
250             faced while they are tried).
251              
252             =back
253              
254             Backend-selection variables (see L</BACKEND SELECTION CRITERIA> for
255             info how they relate to other methods and note that using
256             configuration file is usually recommended over setting those
257             variables):
258              
259             =over 4
260              
261             =item C<PASSWD_KEYRING_FORCE>
262              
263             Use given backend and nothing else. For example, by setting
264             C<PASSWD_KEYRING_FORCE=KDEWallet> user may enforce use of
265             L<Passwd::Keyring::KDEWallet>.
266              
267             This variable is completely ignored if C<force> parameter was
268             specified, and causes runtime error if specified backend is not
269             present, not working, or present on the C<forbid> list.
270              
271             =item C<PASSWD_KEYRING_FORBID>
272              
273             Space separated list of backends to forbid, for example
274             C<PASSWD_KEYRING_FORBID="Gnome KDEWallet">.
275              
276             Ignored if C<force> parameter was specified, otherwise works as this
277             param.
278              
279             =item C<PASSWD_KEYRING_PREFER>
280              
281             Space separated names of backends to prefer.
282              
283             Ignored if C<prefer> parameter was specified, otherwise works as this
284             param.
285              
286             =back
287              
288             =head1 BACKEND SELECTION CRITERIA
289              
290             Backend selection is organized around 3 steering parameters: C<force>,
291             C<forbid>, and C<prefer>. For each of those, the value is looked in
292             the following places (first found is returned):
293              
294             =over 4
295              
296             =item hardcoded value (C<get_keyring> param),
297              
298             =item environment variable (C<PASSWD_KEYRING_...>)
299              
300             =item configuration file per-application setting
301              
302             =item configuration file default setting
303              
304             =item library default
305              
306             =back
307              
308             Each param is calculated separately, so one can have C<prefer>
309             initialized from hardcoded value, C<forbid> taken from the config file
310             and C<force> defined by C<PASSWD_KEYRING_FORCE> environment
311             variable. This may sometimes be confusing so use sparingly (and limit
312             to config file unless you really have reason to do otherwise).
313              
314             Once calculated, those params are used in the following way:
315              
316             =over 4
317              
318             =item if C<force> is set, this is just used and remaining params are ignored - module tries to load this backend and either returns it, or (if it failed) raises an exception;
319              
320             =item elsewhere, all known backends are enumerated, and filtered by C<forbid> (so only those not forbidden remain)
321              
322             =item the remaining list is sorted according to position on C<prefer>
323              
324             =item those modules are tried in order, first which succesfully loaded and initialized is returned
325              
326             =item if nothing was found, module raises exception.
327              
328             =back
329              
330             The following library defaults are used:
331              
332             =over 4
333              
334             =item there is no default for C<force>;
335              
336             =item C<forbid> is calculated according to the operating system (so L<Passwd::Keyring::OSXKeychain> is forbidden everywhere except Mac OS/X, L<Passwd::Keyring::Gnome> is forbidden on Windows and Mac, etc);
337              
338             =item C<prefer> is calculated according to operating system and detected session characteristics (so, if Gnome or Ubuntu session is detected, L<Passwd::Keyring::Gnome> is preferred, and if we have KDE, we prefer L<Passwd::Keyring:KDEWallet>, etc).
339              
340             =back
341              
342             =cut
343              
344             sub get_keyring {
345 7     7 1 3752 my $chooser = Passwd::Keyring::Auto::Chooser->new(@_);
346 7         189 return $chooser->get_keyring();
347             }
348              
349             =head1 FURTHER INFORMATION
350              
351             L<Passwd::Keyring::Auto::KeyringAPI> describes methods available on keyring objects
352             and provides some additional detail on keyring construction.
353              
354             =head1 AUTHOR
355              
356             Marcin Kasperski
357              
358             =head1 BUGS
359              
360             Please report any bugs or feature requests to
361             issue tracker at L<https://bitbucket.org/Mekk/perl-keyring-auto>.
362              
363             =head1 SUPPORT
364              
365             You can find documentation for this module with the perldoc command.
366              
367             perldoc Passwd::Keyring::Auto
368              
369             You can also look for information at:
370              
371             L<http://search.cpan.org/~mekk/Passwd-Keyring-Auto/>
372              
373             Source code is tracked at:
374              
375             L<https://bitbucket.org/Mekk/perl-keyring-auto>
376              
377             =head1 LICENSE AND COPYRIGHT
378              
379             Copyright 2012-2015 Marcin Kasperski.
380              
381             This program is free software; you can redistribute it and/or modify it
382             under the terms of either: the GNU General Public License as published
383             by the Free Software Foundation; or the Artistic License.
384              
385             See http://dev.perl.org/licenses/ for more information.
386              
387              
388             =cut
389              
390             1; # End of Passwd::Keyring::Auto