r6200@rob-kinyons-computer-2 (orig r9980): rkinyon | 2007-09-22 21:02:54 -0400

[dbsrgits/DBM-Deep.git] / lib / DBM / Deep / Cookbook.pod

diff --git a/lib/DBM/Deep/Cookbook.pod b/lib/DBM/Deep/Cookbook.pod
index 61b8163..b82ad8a 100644 (file)
--- a/lib/DBM/Deep/Cookbook.pod
+++ b/lib/DBM/Deep/Cookbook.pod
@@ -26,4 +26,128 @@ In 5.6, you will have to do the following:
 In a future version, you will be able to specify C<utf8 =E<gt> 1> and
 L<DBM::Deep/> will do these things for you.
 
-=end
+=head2 Real-time Encryption Example
+
+Here is a working example that uses the I<Crypt::Blowfish> module to
+do real-time encryption / decryption of keys & values with DBM::Deep Filters.
+Please visit L<http://search.cpan.org/search?module=Crypt::Blowfish> for more
+on I<Crypt::Blowfish>. You'll also need the I<Crypt::CBC> module.
+
+  use DBM::Deep;
+  use Crypt::Blowfish;
+  use Crypt::CBC;
+
+  my $cipher = Crypt::CBC->new({
+      'key'             => 'my secret key',
+      'cipher'          => 'Blowfish',
+      'iv'              => '$KJh#(}q',
+      'regenerate_key'  => 0,
+      'padding'         => 'space',
+      'prepend_iv'      => 0
+  });
+
+  my $db = DBM::Deep->new(
+      file => "foo-encrypt.db",
+      filter_store_key => \&my_encrypt,
+      filter_store_value => \&my_encrypt,
+      filter_fetch_key => \&my_decrypt,
+      filter_fetch_value => \&my_decrypt,
+  );
+
+  $db->{key1} = "value1";
+  $db->{key2} = "value2";
+  print "key1: " . $db->{key1} . "\n";
+  print "key2: " . $db->{key2} . "\n";
+
+  undef $db;
+  exit;
+
+  sub my_encrypt {
+      return $cipher->encrypt( $_[0] );
+  }
+  sub my_decrypt {
+      return $cipher->decrypt( $_[0] );
+  }
+
+=head2 Real-time Compression Example
+
+Here is a working example that uses the I<Compress::Zlib> module to do real-time
+compression / decompression of keys & values with DBM::Deep Filters.
+Please visit L<http://search.cpan.org/search?module=Compress::Zlib> for
+more on I<Compress::Zlib>.
+
+  use DBM::Deep;
+  use Compress::Zlib;
+
+  my $db = DBM::Deep->new(
+      file => "foo-compress.db",
+      filter_store_key => \&my_compress,
+      filter_store_value => \&my_compress,
+      filter_fetch_key => \&my_decompress,
+      filter_fetch_value => \&my_decompress,
+  );
+
+  $db->{key1} = "value1";
+  $db->{key2} = "value2";
+  print "key1: " . $db->{key1} . "\n";
+  print "key2: " . $db->{key2} . "\n";
+
+  undef $db;
+  exit;
+
+  sub my_compress {
+      return Compress::Zlib::memGzip( $_[0] ) ;
+  }
+  sub my_decompress {
+      return Compress::Zlib::memGunzip( $_[0] ) ;
+  }
+
+B<Note:> Filtering of keys only applies to hashes. Array "keys" are
+actually numerical index numbers, and are not filtered.
+
+=head1 Custom Digest Algorithm
+
+DBM::Deep by default uses the I<Message Digest 5> (MD5) algorithm for hashing
+keys. However you can override this, and use another algorithm (such as SHA-256)
+or even write your own. But please note that DBM::Deep currently expects zero
+collisions, so your algorithm has to be I<perfect>, so to speak. Collision
+detection may be introduced in a later version.
+
+You can specify a custom digest algorithm by passing it into the parameter
+list for new(), passing a reference to a subroutine as the 'digest' parameter,
+and the length of the algorithm's hashes (in bytes) as the 'hash_size'
+parameter. Here is a working example that uses a 256-bit hash from the
+I<Digest::SHA256> module. Please see
+L<http://search.cpan.org/search?module=Digest::SHA256> for more information.
+
+  use DBM::Deep;
+  use Digest::SHA256;
+
+  my $context = Digest::SHA256::new(256);
+
+  my $db = DBM::Deep->new(
+      filename => "foo-sha.db",
+      digest => \&my_digest,
+      hash_size => 32,
+  );
+
+  $db->{key1} = "value1";
+  $db->{key2} = "value2";
+  print "key1: " . $db->{key1} . "\n";
+  print "key2: " . $db->{key2} . "\n";
+
+  undef $db;
+  exit;
+
+  sub my_digest {
+      return substr( $context->hash($_[0]), 0, 32 );
+  }
+
+B<Note:> Your returned digest strings must be B<EXACTLY> the number
+of bytes you specify in the hash_size parameter (in this case 32). Undefined
+behavior will occur otherwise.
+
+B<Note:> If you do choose to use a custom digest algorithm, you must set it
+every time you access this file. Otherwise, the default (MD5) will be used.
+
+=cut