Dogcows Code - chaz/p5-File-KDBX/blob - lib/File/KDBX/Key/ChallengeResponse.pm

   1 package File::KDBX::Key::ChallengeResponse;
   2 # ABSTRACT: A challenge-response key
   3
   4 use warnings;
   5 use strict;
   6
   7 use File::KDBX::Error;
   8 use namespace::clean;
   9
  10 use parent 'File::KDBX::Key';
  11
  12 our $VERSION = '999.999'; # VERSION
  13
  14 sub init {
  15     my $self = shift;
  16     my $primitive = shift or throw 'Missing key primitive';
  17
  18     $self->{responder} = $primitive;
  19
  20     return $self->hide;
  21 }
  22
  23 =method raw_key
  24
  25     $raw_key = $key->raw_key;
  26     $raw_key = $key->raw_key($challenge);
  27
  28 Get the raw key which is the response to a challenge. The response will be saved so that subsequent calls
  29 (with or without the challenge) can provide the response without challenging the responder again. Only once
  30 response is saved at a time; if you call this with a different challenge, the new response is saved over any
  31 previous response.
  32
  33 =cut
  34
  35 sub raw_key {
  36     my $self = shift;
  37     if (@_) {
  38         my $challenge = shift // '';
  39         # Don't challenge if we already have the response.
  40         return $self->SUPER::raw_key if $challenge eq ($self->{challenge} // '');
  41         $self->_set_raw_key($self->challenge($challenge, @_));
  42         $self->{challenge} = $challenge;
  43     }
  44     $self->SUPER::raw_key;
  45 }
  46
  47 =method challenge
  48
  49     $response = $key->challenge($challenge, @options);
  50
  51 Issue a challenge and get a response, or throw if the responder failed to provide one.
  52
  53 =cut
  54
  55 sub challenge {
  56     my $self = shift;
  57
  58     my $responder = $self->{responder} or throw 'Cannot issue challenge without a responder';
  59     return $responder->(@_);
  60 }
  61
  62 1;
  63 __END__
  64
  65 =head1 SYNOPSIS
  66
  67     use File::KDBX::Key::ChallengeResponse;
  68
  69     my $responder = sub {
  70         my $challenge = shift;
  71         ...;    # generate a response based on a secret of some sort
  72         return $response;
  73     };
  74     my $key = File::KDBX::Key::ChallengeResponse->new($responder);
  75
  76 =head1 DESCRIPTION
  77
  78 A challenge-response key is kind of like multifactor authentication, except you don't really I<authenticate>
  79 to a KDBX database because it's not a service. Specifically it would be the "what you have" component. It
  80 assumes there is some device that can store a key that is only known to the unlocker of a database.
  81 A challenge is made to the device and the response generated based on the key is used as the raw key.
  82
  83 Inherets methods and attributes from L<File::KDBX::Key>.
  84
  85 This is a generic implementation where a responder subroutine is provided to provide the response. There is
  86 also L<File::KDBX::Key::YubiKey> which is a subclass that allows YubiKeys to be responder devices.
  87
  88 =cut