From 83e242f14c5ae59193211af39c06987af479fc0c Mon Sep 17 00:00:00 2001
From: Jesse Luehrs <doy@tozt.net>
Date: Sun, 19 Dec 2010 11:19:55 -0600
Subject: add docs

---
 lib/KiokuDB/Serializer/Crypt.pm          | 51 ++++++++++++++++++++++++++++++++
 lib/KiokuDB/Serializer/JSON/Crypt.pm     | 21 +++++++++++++
 lib/KiokuDB/Serializer/Storable/Crypt.pm | 21 +++++++++++++
 lib/KiokuDB/Serializer/YAML/Crypt.pm     | 21 +++++++++++++
 4 files changed, 114 insertions(+)

diff --git a/lib/KiokuDB/Serializer/Crypt.pm b/lib/KiokuDB/Serializer/Crypt.pm
index 2aba3cc..983cd0b 100644
--- a/lib/KiokuDB/Serializer/Crypt.pm
+++ b/lib/KiokuDB/Serializer/Crypt.pm
@@ -7,8 +7,33 @@ use Crypt::Util;
 
 =head1 SYNOPSIS
 
+  package My::Serializer;
+  use Moose;
+  with 'KiokuDB::Serializer', 'KiokuDB::Serializer::Crypt';
+
+  sub serialize { ... }
+  sub deserialize { ... }
+
 =head1 DESCRIPTION
 
+This is a role which wraps the C<serialize> and C<deserialize> methods of a
+L<KiokuDB::Serializer> class, encrypting the results before storing them into
+the database, and decrypting them when retrieving them. It can use several
+different encryption schemes (it's based on L<Crypt::Util>, so anything that
+that supports).
+
+Unless you are writing a custom serializer, you probably want to look at the
+classes which consume this role: L<KiokuDB::Serializer::JSON::Crypt>,
+L<KiokuDB::Serializer::YAML::Crypt>, and
+L<KiokuDB::Serializer::Storable::Crypt>.
+
+=cut
+
+=attr crypt_key
+
+The encryption key to use for encrypting and decrypting. Corresponds to
+C<default_key> in L<Crypt::Util>.
+
 =cut
 
 has crypt_key => (
@@ -17,12 +42,30 @@ has crypt_key => (
     required => 1,
 );
 
+=attr crypt_cipher
+
+The encryption cipher to use. Corresponds to C<default_cipher> in
+L<Crypt::Util>, and defaults to C<Rijndael>. You must ensure the appropriate
+cipher backend is installed (by adding, for instance, L<Crypt::Rijndael> to the
+dependency list for your application).
+
+=cut
+
 has crypt_cipher => (
     is       => 'ro',
     isa      => 'Str',
     default  => 'Rijndael',
 );
 
+=attr crypt_mode
+
+The encryption mode to use. Corresponds to C<default_mode> in L<Crypt::Util>,
+and defaults to C<CFB>. You must ensure the appropriate mode backend is
+installed (by adding, for instance, L<Crypt::CFB> to the dependency list for
+your application).
+
+=cut
+
 has crypt_mode => (
     is       => 'ro',
     isa      => 'Str',
@@ -30,6 +73,14 @@ has crypt_mode => (
     default  => 'CFB',
 );
 
+=attr crypt
+
+The L<Crypt::Util> object which will be used for the encryption. Typically,
+this will be automatically created based on the other attribute values, but an
+already-built object can be passed in here for more complicated usages.
+
+=cut
+
 has crypt => (
     is      => 'ro',
     isa     => 'Crypt::Util',
diff --git a/lib/KiokuDB/Serializer/JSON/Crypt.pm b/lib/KiokuDB/Serializer/JSON/Crypt.pm
index 53569bc..8a87fa5 100644
--- a/lib/KiokuDB/Serializer/JSON/Crypt.pm
+++ b/lib/KiokuDB/Serializer/JSON/Crypt.pm
@@ -5,8 +5,29 @@ use namespace::autoclean;
 
 =head1 SYNOPSIS
 
+  use KiokuDB::Util;
+  use KiokuDB::Serializer::JSON::Crypt;
+
+  my $dsn    = '...';
+  my $secret = '...';
+
+  my $backend = KiokuDB::Util::dsn_to_backend(
+      $dsn,
+      serializer => KiokuDB::Serializer::JSON::Crypt->new(
+          crypt_cipher => 'Rijndael',
+          crypt_mode   => 'CFB',
+          crypt_key    => $secret,
+      ),
+  )
+
+  my $d = KiokuDB->new(backend => $backend);
+
 =head1 DESCRIPTION
 
+This serializer class extends L<KiokuDB::Serializer::JSON> to add encryption
+support. See L<KiokuDB::Serializer::Crypt> for an explanation of the allowed
+attributes.
+
 =cut
 
 extends 'KiokuDB::Serializer::JSON';
diff --git a/lib/KiokuDB/Serializer/Storable/Crypt.pm b/lib/KiokuDB/Serializer/Storable/Crypt.pm
index 62da725..4bd17b5 100644
--- a/lib/KiokuDB/Serializer/Storable/Crypt.pm
+++ b/lib/KiokuDB/Serializer/Storable/Crypt.pm
@@ -6,8 +6,29 @@ use namespace::autoclean;
 
 =head1 SYNOPSIS
 
+  use KiokuDB::Util;
+  use KiokuDB::Serializer::Storable::Crypt;
+
+  my $dsn    = '...';
+  my $secret = '...';
+
+  my $backend = KiokuDB::Util::dsn_to_backend(
+      $dsn,
+      serializer => KiokuDB::Serializer::Storable::Crypt->new(
+          crypt_cipher => 'Rijndael',
+          crypt_mode   => 'CFB',
+          crypt_key    => $secret,
+      ),
+  )
+
+  my $d = KiokuDB->new(backend => $backend);
+
 =head1 DESCRIPTION
 
+This serializer class extends L<KiokuDB::Serializer::Storable> to add
+encryption support. See L<KiokuDB::Serializer::Crypt> for an explanation of the
+allowed attributes.
+
 =cut
 
 extends 'KiokuDB::Serializer::Storable';
diff --git a/lib/KiokuDB/Serializer/YAML/Crypt.pm b/lib/KiokuDB/Serializer/YAML/Crypt.pm
index 9902424..5f6f85b 100644
--- a/lib/KiokuDB/Serializer/YAML/Crypt.pm
+++ b/lib/KiokuDB/Serializer/YAML/Crypt.pm
@@ -6,8 +6,29 @@ use namespace::autoclean;
 
 =head1 SYNOPSIS
 
+  use KiokuDB::Util;
+  use KiokuDB::Serializer::YAML::Crypt;
+
+  my $dsn    = '...';
+  my $secret = '...';
+
+  my $backend = KiokuDB::Util::dsn_to_backend(
+      $dsn,
+      serializer => KiokuDB::Serializer::YAML::Crypt->new(
+          crypt_cipher => 'Rijndael',
+          crypt_mode   => 'CFB',
+          crypt_key    => $secret,
+      ),
+  )
+
+  my $d = KiokuDB->new(backend => $backend);
+
 =head1 DESCRIPTION
 
+This serializer class extends L<KiokuDB::Serializer::YAML> to add
+encryption support. See L<KiokuDB::Serializer::Crypt> for an explanation of the
+allowed attributes.
+
 =cut
 
 extends 'KiokuDB::Serializer::YAML';
-- 
cgit v1.2.3-54-g00ecf