From e34214dcace0ecb2d319ed145451db3ac37691db Mon Sep 17 00:00:00 2001
From: Daniel Friesel <derf@finalrewind.org>
Date: Wed, 18 May 2011 12:35:19 +0200
Subject: App::Raps2::Password documentation

---
 lib/App/Raps2/Password.pm | 110 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 110 insertions(+)

diff --git a/lib/App/Raps2/Password.pm b/lib/App/Raps2/Password.pm
index 73258b2..73eee32 100644
--- a/lib/App/Raps2/Password.pm
+++ b/lib/App/Raps2/Password.pm
@@ -11,6 +11,57 @@ use Crypt::Eksblowfish::Bcrypt qw(bcrypt_hash en_base64 de_base64);
 
 our $VERSION = '0.2';
 
+=head1 NAME
+
+App::Raps2::Password - Password class for App::Raps2
+
+=head1 SYNOPSIS
+
+    use App::Raps2::Password;
+
+    my $pass = App::Raps2::Password->new(
+        passphrase => 'secret',
+    );
+
+    my $oneway_hash = $raps2->crypt();
+    $raps2->verify($oneway_hash);
+
+    my $twoway_hash = $raps2->encrypt('data');
+    print $raps2->decrypt($twoway_hash);
+    # "data"
+
+=head1 VERSION
+
+This manual documents B<App::Raps2::Password> version 0.2
+
+=head1 METHODS
+
+=over
+
+=item $pass = App::Raps2::Password->new(I<%conf>)
+
+Creates a new I<App::Raps2::Password> object. You can only have one passphrase
+per object. Arguments:
+
+=over
+
+=item B<cost> => I<int>
+
+Cost to pass to B<Crypt::Eksblowfish>, defaults to 12.
+
+=item B<passphrase> => I<string>
+
+Passphrase to operate with. Mandatory.
+
+=item B<salt> => I<string>
+
+16-byte string to use as salt. If none is specified, B<App::Raps2::Password>
+generates its own.
+
+=back
+
+=cut
+
 sub new {
 	my ($obj, %conf) = @_;
 
@@ -33,6 +84,12 @@ sub new {
 	return bless($ref, $obj);
 }
 
+=item $pass->create_salt()
+
+Returns a new 16-byte salt. Contains only printable characters.
+
+=cut
+
 sub create_salt {
 	my ($self) = @_;
 	my $salt = q{};
@@ -44,6 +101,12 @@ sub create_salt {
 	return $salt;
 }
 
+=item $pass->salt([I<salt>])
+
+Gets/Sets the currently used salt.
+
+=cut
+
 sub salt {
 	my ($self, $salt) = @_;
 
@@ -58,6 +121,13 @@ sub salt {
 	$self->{salt} = $salt;
 }
 
+=item $pass->encrypt(I<data>)
+
+Encrypts I<data> with the passphrase saved in the object, returns the
+corresponding hexadecimal hash (as string).
+
+=cut
+
 sub encrypt {
 	my ($self, $in) = @_;
 
@@ -71,6 +141,12 @@ sub encrypt {
 	return $cbc->encrypt_hex($in);
 }
 
+=item $pass->decrypt(I<hexstr>)
+
+Decrypts I<hexstr> (as created by B<encrypt>), returns its original content.
+
+=cut
+
 sub decrypt {
 	my ($self, $in) = @_;
 
@@ -84,6 +160,12 @@ sub decrypt {
 	return $cbc->decrypt_hex($in);
 }
 
+=item $pass->crypt()
+
+Return a base64 bcrypt hash of the password, salted with the salt.
+
+=cut
+
 sub crypt {
 	my ($self) = @_;
 
@@ -97,6 +179,14 @@ sub crypt {
 	));
 }
 
+=item $pass->verify(I<hash>)
+
+Verify a hash as returned by B<crypt>.
+
+Returns true if it matches, dies if it doesn't.
+
+=cut
+
 sub verify {
 	my ($self, $testhash) = @_;
 
@@ -109,3 +199,23 @@ sub verify {
 }
 
 1;
+
+__END__
+
+=back
+
+=head1 DEPENDENCIES
+
+B<Crypt::CBC>, B<Crypt::Eksblowfish>.
+
+=head1 SEE ALSO
+
+Crypt::CBC(3pm), Crypt::Eksblowfish(3pm).
+
+=head1 AUTHOR
+
+Copyright (C) 2011 by Daniel Friesel E<lt>derf@finalrewind.orgE<gt>
+
+=head1 LICENSE
+
+  0. You just DO WHAT THE FUCK YOU WANT TO.
-- 
cgit v1.2.3