Documentation updates

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<account> 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<raps2> will use the B<pwgen> 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<del> I<account>
 
 Remove I<account> from the store.
@@ -330,7 +336,36 @@ Show version information
 
 =head1 OPTIONS
 
-None.
+=over
+
+=item B<-c>, B<--cost> I<int>
+
+Key setup cost to use for new passwords, overrides the configuration file.
+Only makes sense with B<raps2 add>.
+
+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<raps2 add>, do not print the generated
+password on stdout.
+
+=item B<-p>, B<--pwgen-cmd> I<command>
+
+When the user does not enter a password in B<raps2 add>, it will execute
+I<command> 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<XDG_CONFIG_HOME> and
@@ -349,6 +387,8 @@ B<XDG_DATA_HOME> environment variables.
 
 =over
 
+=item * Config::Tiny
+
 =item * Crypt::CBC
 
 =item * Crypt::Eksblowfish
@@ -368,6 +408,9 @@ B<XDG_DATA_HOME> 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 E<lt>derf@finalrewind.orgE<gt>
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<cost> of key setup, passed on to App::Raps2::Password(3pm).
 
+Default: 12
+
 =item B<no_cli> => I<bool>
 
 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<pwgen_cmd> => I<comand>
+
+Command to use in B<generate_password>.
+
+Default: pwgen -s 23 1
+
 =back
 
+Note that the B<cost> and B<pwgen_cmd> 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<password> if
@@ -334,8 +346,8 @@ specified, otherwise it asks the user via App::Raps2::UI(3pm).
 Load a password from I<file> (or account I<name>), requires
 B<get_master_password> 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<file> => I<file> | B<name> => I<name> )
 
@@ -343,7 +355,7 @@ Load all unencrypted data from I<file> (or account I<name>). Unlike
 B<pw_load>, this method does not require a prior call to
 B<get_master_password>.
 
-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<data> keys are supported:
 
 =item B<salt> => I<salt>
 
+=item B<cost> => I<cost> (optional, inferred from B<new> / the config otherwise)
+
 =item B<file> => I<file> | B<name> => I<name> (one must be set)
 
 =item B<url> => I<url> (optional)
@@ -372,6 +386,16 @@ The following I<data> keys are supported:
 
 Returns the App::Raps2::UI(3pm) object.
 
+=item $raps2->conf(I<key>)
+
+Returns the current config value of I<key>, either set by B<new> or loaded
+from the defaults config file.
+
+=item $raps2->generate_password()
+
+Runs B<pwgen_cmd> (as specified in B<new> 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<new>.
 
+=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<new>.
+
 =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<new>.
 
-Calls B<create_config> if no raps2 config was found.
+Calls B<create_config> and B<create_defaults> 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<raps2>, 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<salt>.
 
-=item $pass->encrypt(I<data>, [I<salt>])
+=item $pass->encrypt(B<data> => I<data>, [B<salt> => I<salt>],
+[B<cost> => I<cost>])
 
 Encrypts I<data> 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<salt> or B<new> will be used. You can override
 it by specifying I<salt>.
 
-=item $pass->decrypt(I<hexstr>, [I<salt>])
+=item $pass->decrypt(B<data> => I<hexstr>, [B<salt> => I<salt>],
+[B<cost> => I<cost>])
 
 Decrypts I<hexstr> (as created by B<encrypt>), returns its original content.