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 File::KDBX::Util qw(:class);
   9 use namespace::clean;
  10
  11 extends 'File::KDBX::Key';
  12
  13 our $VERSION = '0.905'; # VERSION
  14
  15 sub init {
  16     my $self = shift;
  17     my $primitive = shift or throw 'Missing key primitive';
  18
  19     $self->{responder} = $primitive;
  20
  21     return $self->hide;
  22 }
  23
  24
  25 sub raw_key {
  26     my $self = shift;
  27     if (@_) {
  28         my $challenge = shift // '';
  29         # Don't challenge if we already have the response.
  30         return $self->SUPER::raw_key if $challenge eq ($self->{challenge} // '');
  31         $self->_set_raw_key($self->challenge($challenge, @_));
  32         $self->{challenge} = $challenge;
  33     }
  34     $self->SUPER::raw_key;
  35 }
  36
  37
  38 sub challenge {
  39     my $self = shift;
  40
  41     my $responder = $self->{responder} or throw 'Cannot issue challenge without a responder';
  42     return $responder->(@_);
  43 }
  44
  45 1;
  46
  47 __END__
  48
  49 =pod
  50
  51 =encoding UTF-8
  52
  53 =head1 NAME
  54
  55 File::KDBX::Key::ChallengeResponse - A challenge-response key
  56
  57 =head1 VERSION
  58
  59 version 0.905
  60
  61 =head1 SYNOPSIS
  62
  63     use File::KDBX::Key::ChallengeResponse;
  64
  65     my $responder = sub {
  66         my $challenge = shift;
  67         ...;    # generate a response based on a secret of some sort
  68         return $response;
  69     };
  70     my $key = File::KDBX::Key::ChallengeResponse->new($responder);
  71
  72 =head1 DESCRIPTION
  73
  74 A challenge-response key is kind of like multifactor authentication, except you don't really I<authenticate>
  75 to a KDBX database because it's not a service. Specifically it would be the "what you have" component. It
  76 assumes there is some device that can store a key that is only known to the owner of a database. A challenge
  77 is made to the device and the response generated based on the key is used as the raw key.
  78
  79 Inherets methods and attributes from L<File::KDBX::Key>.
  80
  81 This is a generic implementation where a responder subroutine is provided to provide the response. There is
  82 also L<File::KDBX::Key::YubiKey> which is a subclass that allows YubiKeys to be responder devices.
  83
  84 =head1 METHODS
  85
  86 =head2 raw_key
  87
  88     $raw_key = $key->raw_key;
  89     $raw_key = $key->raw_key($challenge);
  90
  91 Get the raw key which is the response to a challenge. The response will be saved so that subsequent calls
  92 (with or without the challenge) can provide the response without challenging the responder again. Only one
  93 response is saved at a time; if you call this with a different challenge, the new response is saved over any
  94 previous response.
  95
  96 =head2 challenge
  97
  98     $response = $key->challenge($challenge, @options);
  99
 100 Issue a challenge and get a response, or throw if the responder failed to provide one.
 101
 102 =head1 BUGS
 103
 104 Please report any bugs or feature requests on the bugtracker website
 105 L<https://github.com/chazmcgarvey/File-KDBX/issues>
 106
 107 When submitting a bug or request, please include a test-file or a
 108 patch to an existing test-file that illustrates the bug or desired
 109 feature.
 110
 111 =head1 AUTHOR
 112
 113 Charles McGarvey <ccm@cpan.org>
 114
 115 =head1 COPYRIGHT AND LICENSE
 116
 117 This software is copyright (c) 2022 by Charles McGarvey.
 118
 119 This is free software; you can redistribute it and/or modify it under
 120 the same terms as the Perl 5 programming language system itself.
 121
 122 =cut