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

diff --git a/lib/File/KDBX/Key/ChallengeResponse.pm b/lib/File/KDBX/Key/ChallengeResponse.pm
index b17a35c..f9b2d48 100644
--- a/lib/File/KDBX/Key/ChallengeResponse.pm
+++ b/lib/File/KDBX/Key/ChallengeResponse.pm
@@ -20,6 +20,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 once
+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 +48,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 +64,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 unlocker 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