X-Git-Url: https://git.dogcows.com/gitweb?p=chaz%2Fp5-File-KDBX;a=blobdiff_plain;f=lib%2FFile%2FKDBX%2FKey%2FChallengeResponse.pm;h=ebf10b796f692ab40c4cfc7f2e43cb64edeb587e;hp=b17a35cbaf2c9b93fbdae11e8db20e83687beaa6;hb=63d73bf382edfb0089b36a45193fc2835cb58b6d;hpb=f63182fc62b25269b1c38588dca2b3535ed1a1a2

diff --git a/lib/File/KDBX/Key/ChallengeResponse.pm b/lib/File/KDBX/Key/ChallengeResponse.pm
index b17a35c..ebf10b7 100644
--- a/lib/File/KDBX/Key/ChallengeResponse.pm
+++ b/lib/File/KDBX/Key/ChallengeResponse.pm
@@ -5,9 +5,10 @@ use warnings;
 use strict;
 
 use File::KDBX::Error;
+use File::KDBX::Util qw(:class);
 use namespace::clean;
 
-use parent 'File::KDBX::Key';
+extends 'File::KDBX::Key';
 
 our $VERSION = '999.999'; # VERSION
 
@@ -20,6 +21,18 @@ sub init {
     return $self->hide;
 }
 
+=method raw_key
+
+    $raw_key = $key->raw_key;
+    $raw_key = $key->raw_key($challenge);
+
+Get the raw key which is the response to a challenge. The response will be saved so that subsequent calls
+(with or without the challenge) can provide the response without challenging the responder again. Only one
+response is saved at a time; if you call this with a different challenge, the new response is saved over any
+previous response.
+
+=cut
+
 sub raw_key {
     my $self = shift;
     if (@_) {
@@ -36,7 +49,7 @@ sub raw_key {
 
     $response = $key->challenge($challenge, @options);
 
-Issue a challenge and get a response, or throw if the responder failed.
+Issue a challenge and get a response, or throw if the responder failed to provide one.
 
 =cut
 
@@ -52,10 +65,25 @@ __END__
 
 =head1 SYNOPSIS
 
-    my $key = File::KDBX::Key::ChallengeResponse->(
-        responder => sub { my $challenge = shift; ...; return $response },
-    );
+    use File::KDBX::Key::ChallengeResponse;
+
+    my $responder = sub {
+        my $challenge = shift;
+        ...;    # generate a response based on a secret of some sort
+        return $response;
+    };
+    my $key = File::KDBX::Key::ChallengeResponse->new($responder);
 
 =head1 DESCRIPTION
 
+A challenge-response key is kind of like multifactor authentication, except you don't really I<authenticate>
+to a KDBX database because it's not a service. Specifically it would be the "what you have" component. It
+assumes there is some device that can store a key that is only known to the owner of a database. A challenge
+is made to the device and the response generated based on the key is used as the raw key.
+
+Inherets methods and attributes from L<File::KDBX::Key>.
+
+This is a generic implementation where a responder subroutine is provided to provide the response. There is
+also L<File::KDBX::Key::YubiKey> which is a subclass that allows YubiKeys to be responder devices.
+
 =cut