From 0053cb1bd48b8aa7e3535045f99f24a562f5d264 Mon Sep 17 00:00:00 2001 From: Daniel Friesel Date: Wed, 20 Jul 2011 21:02:30 +0200 Subject: Documentation updates --- Build.PL | 1 + bin/raps2 | 53 ++++++++++++++++++++++++++++++++++++++++++----- lib/App/Raps2.pm | 45 +++++++++++++++++++++++++++++++++++----- lib/App/Raps2/Password.pm | 6 ++++-- 4 files changed, 93 insertions(+), 12 deletions(-) diff --git a/Build.PL b/Build.PL index cc82474..9d222d4 100644 --- a/Build.PL +++ b/Build.PL @@ -16,6 +16,7 @@ my $build = Module::Build->new( requires => { 'perl' => '5.10.0', 'Carp' => 0, + 'Config::Tiny' => 0, 'Crypt::CBC' => 0, 'Crypt::Eksblowfish' => 0, 'Crypt::Eksblowfish::Bcrypt' => 0, diff --git a/bin/raps2 b/bin/raps2 index 2451e6f..f18b539 100755 --- a/bin/raps2 +++ b/bin/raps2 @@ -11,15 +11,15 @@ use File::BaseDir qw(data_files data_home); use File::Slurp qw(read_dir); use Getopt::Long qw(:config no_ignore_case); -my ( $default_cost, $echo_generated, $pwgen_cmd ); +my ( $default_cost, $no_echo, $pwgen_cmd ); our $VERSION = '0.50'; GetOptions( 'c|cost=i' => \$default_cost, - 'e|echo' => \$echo_generated, + 'E|no-echo' => \$no_echo, 'h|help' => sub { cmd_help(0) }, - 'p|pwgen_cmd=s' => \$pwgen_cmd, + 'p|pwgen-cmd=s' => \$pwgen_cmd, 'V|version' => sub { say "raps2 version ${VERSION}"; exit 0 }, ) or cmd_help(1); @@ -79,7 +79,7 @@ sub cmd_add { exit 3; } - if ($echo_generated) { + if ( not $no_echo ) { $raps2->ui->output( [ 'Generated password', $pass ] ); } } @@ -294,6 +294,12 @@ and Login will be saved as plaintext, Extra is encrypted like the password. Adds I to the store. It will ask you for the store's master password, some metadata and the new password and then store them. +If you do not provide a password (that is, leave both "Password" and "Verify" +lines blank), B will use the B command to create one for you and +print the generated password on stdout. + +See also the B<-c>, B<-E> and B<-p> options. + =item B I Remove I from the store. @@ -330,7 +336,36 @@ Show version information =head1 OPTIONS -None. +=over + +=item B<-c>, B<--cost> I + +Key setup cost to use for new passwords, overrides the configuration file. +Only makes sense with B. + +Please be aware that the key setup time is an exponential function. That is, +when you increment the cost by 1, the key setup time will double. See +Crypt::Eksblowfish(3pm). + +Default: 12 + +=item B<-E>, B<--no-echo> + +When using the pwgen functionality of B, do not print the generated +password on stdout. + +=item B<-p>, B<--pwgen-cmd> I + +When the user does not enter a password in B, it will execute +I to create one. The first line of output is taken as password. + +Default: pwgen -s 23 1 + +=item B<-V>, B<--version> + +Show version information. + +=back =head1 EXIT STATUS @@ -340,6 +375,9 @@ zero on success, non-zero otherwise. raps2 saves the master password hash in F<~/.config/raps2/password>. +The configuation (key setup cost and pwgen command) is stored in +F<~/.config/raps2/defaults> in an INI-like format. + Additional encrypted passwords are stored in F<~/.local/share/raps2/>. These directories can be changed by setting the B and @@ -349,6 +387,8 @@ B environment variables. =over +=item * Config::Tiny + =item * Crypt::CBC =item * Crypt::Eksblowfish @@ -368,6 +408,9 @@ B environment variables. This is alpha software, the store format may change without further notice. Backwards-compatibility is not guaranteed. +When running for the first time, raps2 will ask for the master passphrase +three times. Two would be better. + =head1 AUTHOR Copyright (C) 2011 by Daniel Friesel Ederf@finalrewind.orgE diff --git a/lib/App/Raps2.pm b/lib/App/Raps2.pm index 897e62e..dd00e54 100644 --- a/lib/App/Raps2.pm +++ b/lib/App/Raps2.pm @@ -275,6 +275,7 @@ sub pw_load_info { url => $key->{url}, login => $key->{login}, salt => $key->{salt}, + cost => $key->{cost}, }; } @@ -316,14 +317,25 @@ Accepted configuration parameters are: B of key setup, passed on to App::Raps2::Password(3pm). +Default: 12 + =item B => I If set to true, App::Raps2 assumes it will not be used as a CLI. It won't initialize its Term::ReadLine object and won't try to read anything from the terminal. +=item B => I + +Command to use in B. + +Default: pwgen -s 23 1 + =back +Note that the B and B options specified here take precedence +over those loaded from the config file. + =item $raps2->get_master_password( [I<$password>] ) Sets the master password used to encrypt all accounts. Uses I if @@ -334,8 +346,8 @@ specified, otherwise it asks the user via App::Raps2::UI(3pm). Load a password from I (or account I), requires B to have been called before. -Returns a hashref containing its url, login, salt and decrypted password and -extra. +Returns a hashref containing its url, login, salt, cost and decrypted password +and extra. =item $raps2->pw_load_info( B => I | B => I ) @@ -343,7 +355,7 @@ Load all unencrypted data from I (or account I). Unlike B, this method does not require a prior call to B. -Returns a hashref with url, login and salt. +Returns a hashref with url, login, salt and cost. =item $raps2->pw_save( I<%data> ) @@ -358,6 +370,8 @@ The following I keys are supported: =item B => I +=item B => I (optional, inferred from B / the config otherwise) + =item B => I | B => I (one must be set) =item B => I (optional) @@ -372,6 +386,16 @@ The following I keys are supported: Returns the App::Raps2::UI(3pm) object. +=item $raps2->conf(I) + +Returns the current config value of I, either set by B or loaded +from the defaults config file. + +=item $raps2->generate_password() + +Runs B (as specified in B or the config file) and returns its +first line of output, without the trailing newline. + =back =head2 INTERNAL @@ -382,12 +406,21 @@ You usually don't need to call these methods by yourself. =item $raps2->create_config() -Creates a default config and asks the user to set a master password. +Creates a password file and asks the user to set a master password. =item $raps2->load_config() Load config. Automatically called by B. +=item $raps2->create_defaults() + +Creates a defaults config file containing the default key setup cost and pwgen +command. + +=item $raps2->load_defaults() + +Loads the defaults file. Automatically called by B. + =item $raps2->pw() Returns the App::Raps2::Password(3pm) object. @@ -403,7 +436,7 @@ Create working directories (~/.config/raps2 and ~/.local/share/raps2, or the respective XDG environment variable contents), if they don't exist yet. Automatically called by B. -Calls B if no raps2 config was found. +Calls B and B if no configs were found. =back @@ -420,6 +453,8 @@ File::Slurp(3pm). =head1 BUGS AND LIMITATIONS Be aware that the password handling API is not yet stable. +Also, so far the development concentrated on B, so this module / its +documentation may not be completely up-to-date. =head1 AUTHOR diff --git a/lib/App/Raps2/Password.pm b/lib/App/Raps2/Password.pm index d80a138..fb73255 100644 --- a/lib/App/Raps2/Password.pm +++ b/lib/App/Raps2/Password.pm @@ -175,7 +175,8 @@ Returns a new 16-byte salt. Contains only printable characters. Returns the currently used salt and optionally changes it to I. -=item $pass->encrypt(I, [I]) +=item $pass->encrypt(B => I, [B => I], +[B => I]) Encrypts I with the passphrase saved in the object, returns the corresponding hexadecimal hash (as string). @@ -183,7 +184,8 @@ corresponding hexadecimal hash (as string). By default, the salt set in B or B will be used. You can override it by specifying I. -=item $pass->decrypt(I, [I]) +=item $pass->decrypt(B => I, [B => I], +[B => I]) Decrypts I (as created by B), returns its original content. -- cgit v1.2.3