Add key file saving and refactor some stuff

[chaz/p5-File-KDBX] / lib / File / KDBX / Key / ChallengeResponse.pm

diff --git a/lib/File/KDBX/Key/ChallengeResponse.pm b/lib/File/KDBX/Key/ChallengeResponse.pm
index b17a35cbaf2c9b93fbdae11e8db20e83687beaa6..f9b2d483119b213319e313bd1870e7750bc0dbdd 100644 (file)
--- 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